Files and the canvas

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>/
  report.md              files the user keeps
  data/sales.csv
  apps/burnup/           apps the agent built
  skills/<name>/         skills the user created
  .tmp/                  scratch, hidden and cleaned up
  .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.

llm = cycls.LLM().allowed_tools(["Bash", "Editor", "Canvas"])

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

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

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

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:

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.

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, multipart
`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}.

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

A shared chat carries the files it references, so a recipient can open the artifact without an account. Forking lands in the forker’s active workspace.

Connectors and MCP

Let a user connect an account, then give tools the credential.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Files and the canvas

Where files live

Opening a file on the canvas

What the canvas renders

Configuring office rendering

Uploads

The HTTP API

Next

Connectors and MCP

​Where files live

​Opening a file on the canvas

​What the canvas renders

​Configuring office rendering

​Uploads

​The HTTP API

​Sharing

​Next

Connectors and MCP

Where files live

Opening a file on the canvas

What the canvas renders

Configuring office rendering

Uploads

The HTTP API

Sharing

Next