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>/
  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}.

Sharing

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.

Next

Connectors and MCP

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