Docs navigation
Agent

File system

File system is the agent's shared folder, labeled Filesystem in the agent sidebar. Upload files here when the agent needs documents, examples, datasets, scripts, or other durable artifacts across its tasks.

How to use file system
UI
  1. 01In the agent sidebar, turn on the Filesystem switch so the shared folder mounts into the agent's tasks.
  2. 02Open Filesystem.
  3. 03Upload files, or drag files into the file browser.
  4. 04Open text files to preview their contents.
  5. 05Download files when you need to inspect or reuse an artifact locally.
Turn on the Filesystem switch
The shared folder mounts into a task's sandbox only while the Filesystem switch is on (shared_folder_enabled: true on the agent through the API). With the switch off you can still browse and upload files, but tasks do not see them. Shared folders are not available on the E2B, Modal, Brainbase Sandbox, or AWS MicroVM sandbox providers.

What file system is for

  • Input files: PDFs, CSVs, spreadsheets, transcripts, images, and other task material.
  • Reference files: Templates, examples, schemas, source documents, and approved samples.
  • Working artifacts: Files the agent creates, edits, or reuses across tasks.

Add files

Upload files from the Filesystem page. Files stay available to the agent across tasks, so use this area for material the agent should be able to find again later. You can upload multiple files at once or drop files directly onto the browser.

Shared files support uploads up to 25 MiB and downloads up to 50 MiB per file. These limits apply on the agent's Filesystem page and to Shared/... in a task's Filesystem tab.

Inspect files

Use the file tree to browse folders, refresh the listing, preview common text files, and download any file. Non-text files download instead of opening in the preview pane.

Downloads from the shared folder contain the current contents, including the agent's edits.

Unavailable task sandbox
If a task's Daytona sandbox no longer exists, its file listing, tree, metadata, and download endpoints return HTTP 409 with detail.code: machine_terminal and detail.message: task's machine is no longer available. This response has no Retry-After header and does not recreate the sandbox or restore Shared files. A missing file in an existing sandbox still returns HTTP 404. Authentication and task access requirements are unchanged.
Runtime path
Inside a task, the shared folder is mounted at /workspace/Shared, and its path is also available in the BRAINBASE_SHARED_DIR environment variable. The file browser shows the same folder.

Protected hosted tasks

Disabled by default
Published Shared snapshots are a separate, disabled-by-default hosted capability. They require operator verification within the internal canary before use. The ordinary Filesystem behavior described above remains unchanged for tasks that have not adopted a snapshot and are outside strict admission and the Shared canary.

An agent manager can publish selected Shared files as an immutable version and explicitly adopt that version into a fresh task. Each adopted task gets its own writable copy at /workspace/Shared. Its edits persist in that task; they do not change the published version, the agent's Filesystem, or another task. Publishing a newer version does not update existing tasks automatically.

Publication and adoption use the management API from your own signed-in session. Worker credentials cannot publish or adopt. A snapshot contains up to 1,000 regular files and 16 MiB of decoded content in total, with relative paths. Hidden directories and links are rejected. Include only files you intend to publish; exclude credential stores. Oversized or unsupported input is rejected without changing the source files.

For an enrolled hosted agent with Shared snapshots enabled and its Shared folder setting on, create an empty task with POST /v2/tasks and body {"agent_id": "<agent ID>", "auto_run": false}. Creation leaves its sandbox unprovisioned, including when global strict admission is off. From the same authorized management session, adopt the chosen version with POST /v2/tasks/{task_id}/shared-snapshot with {"snapshot_id": "<published snapshot ID>"}, then send the first message. Creating a task does not choose or adopt a snapshot automatically.

Adoption requires a new task that has never created a sandbox and whose creation the service can verify. Choose another new task to use a different version. Existing tasks, their private edits, and the original Shared folder are retained for recovery. When strict admission is enabled, a task without a verified private Shared copy stays blocked. A lost sandbox is not silently replaced with an older copy of its files.

Best practices

  • Use descriptive filenames so the agent can identify the right file.
  • Keep canonical instructions in Instructions or Playbooks; use files for artifacts and examples.
  • Remove stale files that could cause the agent to use outdated context.
  • Store credentials in Secrets, not uploaded files.
  • Upload small, focused files when possible so the agent can inspect them efficiently.