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

# Files and the canvas

> Every user gets a workspace of files. The canvas renders spreadsheets, documents, slides, PDFs, images and HTML without leaving the chat.

Each user of an agent gets a file tree on the volume mounted at `/workspace`. The
`Editor` and `Bash` tools read and write it, the files panel lists it, and the
canvas renders one file at a time beside the conversation.

## Where files live

```
/workspace/<user or workspace scope>/
  AGENT.md               instructions, opened from the right panel, not listed in Files
  report.md              files the user keeps
  media/                 images and videos added to report.md in the editor
  data/sales.csv
  apps/burnup/           apps the agent built
  skill-drafts/<name>/   skills the agent writes before publishing them
  .tmp/                  scratch, hidden and cleaned up
  .skills/  .apps/       published skills and app data, managed and hidden
  .db/                   chat store, not readable from the sandbox
```

Paths in tools are workspace relative. `~/report.md` and `/workspace/report.md`
both resolve to the same file, traversal outside the workspace is refused, and
`/tmp` raises an explicit error because every bash command gets its own `/tmp`
that no other tool can see.

Scratch belongs in `.tmp/`. It is hidden from the files panel and cleaned up, so
intermediate downloads and working data do not clutter what the user sees.

## Opening a file on the canvas

The `Canvas` tool opens one finished file in the side panel.

```python theme={null}
llm = cycls.LLM().allowed_tools(["Bash", "Editor", "Canvas"])
```

From a custom loop, or from your own code, the same action is a `ui` event:

```python theme={null}
yield {"type": "ui", "action": "open_canvas", "path": "report.xlsx"}
```

## What the canvas renders

| File type | Rendered as | Where the work happens |
| - | - | - |
| `csv`, `tsv`, `xls`, `xlsx`, `xlsm`, `ods` | interactive grid with sheet tabs | in the browser |
| `docx` | formatted document with pages, fonts, tables and images | in the browser |
| `ppt`, `pptx`, `odp` | slide viewer with a thumbnail rail | office render service |
| `doc`, `odt`, `rtf`, `epub` | read-only PDF | office render service |
| `pdf` | PDF viewer | in the browser |
| `md`, `html`, images, audio, video, `glb`, `gltf`, code and text | native viewer | in the browser |
| anything else | download card | |

Any failure, including an unreachable service or an unparseable file, falls back
to the download card rather than an error page.

## Editing on the canvas

Text files open with an **Edit** button. Markdown opens in a rich editor with a
toolbar, a `/` menu for inserting blocks, and drag handles for moving them. It
covers headings, lists, checklists, tables, quotes, code, links and dividers, and
saving writes plain markdown back to the file. Right-clicking a table cell adds or
deletes a row or column, or deletes the table, and the toolbar can delete a table
too. Each block takes its direction from its own text, so Arabic and English
paragraphs sit side by side, and the `/` menu opens under Arabic text as it does
under English.

Images and videos pasted, dropped or picked into a document are saved in a
`media/` folder beside it and linked by a relative path. The canvas shows those
images and plays those videos in the markdown view too.

Markdown that contains math, raw HTML or footnotes opens in a plain-text editor
instead, so saving cannot drop them. Other text and code files also edit as plain
text. Every other format on the canvas is view-only.

## Configuring office rendering

Spreadsheets and `.docx` render from raw bytes in the browser and need no
service. Presentations and the PDF fallback call a shared render service,
configured with two environment variables:

```bash theme={null}
OFFICE_RENDER_URL=https://office-render.cycls.ai
OFFICE_RENDER_SECRET=your_shared_secret
```

With either unset, those two paths return a download card and everything else
keeps working.

LibreOffice is about 1GB and is used by a small fraction of turns, which is why
it runs in one shared service rather than inside every agent image. Rendered
output is cached under a hidden `.cache/office/` directory in the workspace, so
reopening a deck does not repay the conversion.

## Uploads

Users attach files in the composer. The loop ingests them before the model call:
images and PDFs go to the model as media when `.vision(True)`, and every
attachment is written into the workspace so tools can open it.

```python theme={null}
web = cycls.Web().max_upload(256)    # MB per file, default 512
```

For text-only models, set `.vision(False)`. The attachment stays in the
workspace and the model receives a note naming the file, which it can then read
with a tool.

## The HTTP API

Files are also a REST surface, which is what the files panel and mobile clients
use. All routes require auth.

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/files?path=subdir` | list a directory |
| `GET` | `/files/{path}` | download, add `?download` for an attachment header |
| `PUT` | `/files/{path}` | upload, the raw body is the file, multipart is also accepted |
| `PATCH` | `/files/{path}` | rename, body `{"to": "new/path"}` |
| `POST` | `/files/{path}` | create a directory |
| `DELETE` | `/files/{path}` | delete, which moves the file to trash |

Deleting moves a file to trash and keeps it restorable for thirty days through
`GET /trash`, `POST /trash/{id}/restore` and `DELETE /trash/{id}`.

## Sharing

```
POST   /share                        create a share link
GET    /share                        list share links
DELETE /share/{token}                revoke
GET    /shared/{user}/{token}        the shared page
POST   /share/{user}/{token}/fork    copy the conversation into the viewer's workspace
```

`POST /share` takes a `path`, either `chat/<id>` or `file/<path>`, and an
`audience`, either `public`, the default, or `org:<id>` for members of that
organization only. The [agent HTTP API](https://docs.cycls.com/reference/agent-api.md#sharing) lists the
rest of the share routes.

A shared chat carries the files it references, so a recipient can open the
artifact without an account. Only chats fork, and a fork lands in the forker's
active workspace.

The shared page has one bar: the Cycls logo, the file's name, who shared it and
when, **Open in new tab** for HTML, **Download**, and one button named after the
agent's brand. A signed-out visitor gets **Sign in**, which returns to the share
afterwards, and Google One Tap when the agent turns it on. A signed-in visitor gets
**Go to Atlas**, and an agent without sign-in shows **Try Atlas**. The page follows
the system's light or dark theme. A
shared file fills the rest of the screen. A shared chat, and the loading and error
pages, use the same bar, and a chat keeps **Continue this conversation**. The page
is translated to Arabic. An org-only link asks a signed-out visitor to sign in,
and tells someone signed in outside the organization "This link isn't shared with
your account".

## Next

> [card] [Connectors and MCP](https://docs.cycls.com/agents/connectors.md)
>
> Let a user connect an account, then give tools the credential.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.