Skip to main content
Filesystems are one of the core TerminalUse primitives. They deserve a concept page, not just endpoint docs.

​
The Model

  • A filesystem is persistent storage.
  • A task can attach a filesystem.
  • The task sees that filesystem at /workspace.
That means /workspace is a runtime mount of a persistent resource, not just a scratch directory.

​
Three Different File Flows

​
1. Whole-Filesystem Archive Flow

Use this for directory-level push and pull.
  • tu fs push
  • tu fs pull
  • get_upload_url
  • get_download_url
These flows move archives, not individual files.

​
2. Single-File Flow

Use this for exact path-level reads and writes.
  • upload_file
  • download_file
  • get_file
  • list_files
This is the right surface when you want one path, one payload, or conditional write semantics.

​
3. Runtime Sync Flow

Use this inside Python agent code when you need explicit sync during handler execution.
  • adk.filesystem.sync_down
  • adk.filesystem.sync_up
  • adk.task.sync_down_system_folder
  • adk.task.sync_up_system_folder

​
Writable vs Read-Only /workspace

/workspace is not always writable.
  • writable when the caller can update the attached filesystem
  • read-only when the caller can run the task but lacks update permission
  • tmpfs when no filesystem is attached

​
Projects Matter

Filesystems inherit their permission boundary from the parent project. If you are designing a multi-tenant or access-controlled app, project design is part of the filesystem model.