> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvas

> Files agents drop into the workspace for you to view in the app.

The **Canvas** is a directory the agent can drop files into and have them appear, typed and clickable, in the app provenance pane. Use it for plans, design docs, HTML reports, and small media. Markdown files written here show up the same way [Plan Mode](/features/workspaces/plan-mode) plans always have; Plan Mode is just one workflow that uses the Canvas.

## Location

`~/.replicas/canvas/` on the workspace VM. Files are listed in the **Canvas** tab at the bottom of the right-side provenance pane, beside **Subagents** and **Terminal**. Nested folders appear as expandable rows. Uploaded media appears in the expandable **media** folder. The agent's live task checklist appears in chat as it is updated.

Attach supported non-image files from the new-workspace prompt or an existing chat to save them directly to `~/.replicas/canvas/` before the message is delivered. They appear in the **Canvas** tab. Click the paperclip menu in a workspace chat, then choose **Attach folder** to attach a directory. Folder-relative paths are preserved under Canvas. Non-image attachments are limited to **50 files**, **50MB** total, and **25MB** per file.

Attachments sent while a workspace is preparing or sleeping are queued until it is active. Sending the related message wakes a sleeping workspace, and the files are placed in Canvas before that message is delivered. Archived workspaces must be [restored](/features/workspaces/overview#sleep-and-wake) before you send attachments or messages.

The Canvas replaces the older `~/.replicas/plans/` directory; the app, engine, and CLI all ship together, so existing workspaces pick up the new path on their next sandbox boot with no migration needed. If you have agents or scripts hard-coded against `~/.replicas/plans/`, point them at `~/.replicas/canvas/` going forward.

## Supported kinds

| Extension                                                                                   | Kind     | Pill    |
| ------------------------------------------------------------------------------------------- | -------- | ------- |
| `.md`, `.markdown`                                                                          | markdown | Plan    |
| `.mmd`, `.mermaid`                                                                          | mermaid  | Diagram |
| `.html`, `.htm`                                                                             | html     | Page    |
| `.txt`, `.log`, `.csv`, `.tsv`, `.json`, `.json5`, `.yaml`, `.yml`, `.toml`, `.ini`, `.xml` | text     | Text    |
| `.png`, `.apng`, `.avif`, `.bmp`, `.ico`, `.jpg`, `.jpeg`, `.jfif`, `.gif`, `.webp`, `.svg` | image    | Image   |
| `.pdf`                                                                                      | pdf      | PDF     |
| `.mp4`, `.webm`, `.mov`                                                                     | video    | Video   |
| `.mp3`, `.wav`, `.ogg`                                                                      | audio    | Audio   |

Clicking an item opens it in the main viewport. Markdown and Mermaid files have **Raw** and **Formatted** views. HTML renders inside a sandboxed iframe, PDFs and images render inline, and media plays in place.

Compatible text files open as editable source. Select **Save** or press `Cmd`/`Ctrl` + `S` to write changes. If the agent changes the file while you edit, its latest changes are folded into your draft automatically.

On desktop, click **Open beside chat** in a Canvas or media viewer to move the artifact into a resizable pane beside the conversation. Select another Canvas or media item to replace the artifact in the split pane. Click **Close split view** to return to the standard layout.

For uploaded images in the **media** folder, use the zoom buttons beside **Download** to scale the preview from 25% to 200%.

To link a self-contained HTML page from a pull request, upload the same file with `replicas media upload <page.html> --name "<name>" --access organization` and use the printed **Forge link**. The page requires Replicas sign-in and membership in the workspace organization; public access is not supported for HTML. See the [Media API](/features/api#media) for authenticated download and inline-preview URLs.

Hovering a row in the Canvas list also reveals a download button on the right, so you can pull the original file out of the workspace without first opening it.

Canvas items remain available after the workspace sleeps when [Data Retention](/admin/data-retention) is enabled.

## Size limits

Each item is capped at **25MB**. Folder selections are additionally capped at **50 files** and **50MB** total. Items over **5MB** remain available to the agent but cannot be previewed or downloaded through Canvas. Use [`replicas media upload`](/features/cli) to share larger media as an inline embed plus an app deep-link in chat; the artifact appears in the chat reply and the **media** folder in Canvas.

## API

The Canvas is exposed by the [API](/features/api#canvas):

* `GET /v1/replica/{id}/canvas` lists items
* `GET /v1/replica/{id}/canvas/{filename}` reads one item
* `PUT /v1/workspaces/{id}/canvas/{filename}` saves a text item
* `POST /v1/workspaces/{id}/canvas` uploads an item immediately or queues it until the related message wakes a sleeping workspace