Skip to main content
By default, an agent starts each run from a clean slate. Agent Filesystem changes that: when it’s enabled, the agent’s workspace persists between runs, so files, notes, and tool state carry forward instead of resetting every time.

​
Viewing Files

The files in an agent’s workspace are viewable directly in the UI, where you can browse the workspace, preview files, and download them.

​
Persisting Files Across Runs

Turning on Agent Filesystem keeps an agent’s workspace between runs. This is useful when an agent should:
  • Build on prior work instead of starting over each run
  • Reuse reference files, lookup tables, or templates you upload once
  • Keep packages or scripts it installed available for later runs

​
Enabling It

1

Open the agent

Go to Agents and open the agent you want to update.
2

Turn on Agent Filesystem

Find the Agent Filesystem card and flip the toggle to On.On the agents and detections list pages, you can also use Learn more on the Agent Filesystem banner to enable it for several agents at once.
3

Manage the files

Once enabled, the agent gets a persistent workspace panel where you can browse, upload, download, and delete files.

​
Managing the Persistent Workspace

From the workspace panel you can:
  • Upload files with the Upload button or by dragging them onto the panel
  • Download any file, or a whole folder as a zip
  • Delete files and folders you no longer need
  • Preview text, markdown, and image files without downloading
Files you upload and files the agent creates share the same workspace, so the agent can pick up where it left off.
Use the persistent workspace for files that should stick around, like reference data or reusable scripts. Keep large, run-specific scratch output (such as raw logs) out of it so the workspace stays tidy.

​
Agent Filesystem vs File Attachments

These are related but separate: See File Attachments for uploading files directly to a chat message.

​
Passing result files to a parent agent

Built-in subagents share their parent’s sandbox. A separately configured agent called through agentTools has its own sandbox and persistent workspace. Both named agents and dynamic subagents can publish a result file with sandbox_publishOutput. This tool is available only during named-child executions and dynamic subagents (including those delegated by a user chat), not top-level runs or user chats:
This snapshots the file’s exact bytes into durable storage. The child should check that publication succeeded and keep its final response short. It does not need to print, copy, or base64-encode the file into its response. Changes to the source file after publication do not change the snapshot; publishing the same name again replaces it. When the child completes successfully, Cotool copies its published files into /workspace/.cotool/agent-results/<child-run-id>/outputs/ in the parent sandbox. The parent receives the paths, byte lengths, and SHA-256 hashes in the tool result (outputFiles in the stored agent result). It can read those files directly with code. Cotool also saves final-message.txt and, when available, structured-output.json in the run’s result directory. Large inline responses are previews; these files contain the complete stored results. Publication supports regular files within the child’s workspace mounts, up to 16 named files and 10 MiB total per child run. Symlinks are rejected. Final-message and structured-output files each have a separate 10 MiB limit. Structured output remains model-generated; saving it preserves the generated result, not an independently computed source file. Published snapshots survive worker restarts and do not require the child’s sandbox to remain alive. Delivery retries use the same destination paths and verify file lengths and hashes. A failed or incomplete publication must be successfully republished; otherwise the handoff fails. After delivery retries are exhausted, the parent receives a tool error rather than a successful result. Parents should require a successful handoff before sending notifications or updating durable state; partial destination files from a failed transfer must not be used. This does not provide atomic notifications or locking between runs.