Skip to main content
Do this when the agent’s work starts from data you already have — a CSV to analyse, a document to summarize, an archive to inspect. The files are staged, copied into the task’s own workspace, and materialized onto the sandbox filesystem before the first command runs. Do not use this to give an agent standing reference material that every task needs. That belongs in the organization context store, which agents read without it being attached per task.

​
Prerequisites

  • A configured object store behind the artifact service
  • An agent equipped with a tool that reads files — the shell (agentarea/shell) or the file tool (agentarea/files)
  • The file model for how task scoping works

​
Steps

1

Stage the file and get a ref

Two ways, and they produce the same kind of staging/{id}/{filename} ref.Server-proxied, for small files and quick scripting. One request, no checksum to compute, but the bytes pass through the API process:
The response carries ref, filename, size, sha256, and content_type.Presigned direct upload, for large files or when you want content verification. Pick this when the file is big enough that proxying it is wasteful, or when you want the store itself to reject a corrupted body:
The response gives ref, upload_url, and expires_in (3600 seconds). The declared SHA-256 is bound into the signature as ChecksumSHA256, so the object store rejects a body that does not hash to it. Upload with:
2

Create the task with the refs

Pass the refs in attachments:
The API HEADs each ref to resolve its verified digest, size, and content type, then copies it server-side into the task’s content-addressed store. The bytes never transit the API process on this leg.
3

Let the agent find them

Each attachment lands at inputs/attachments/<filename>, and the agent is told so in its prompt — the exact relative paths are listed, with instructions not to ask for the files again. Before the first bash command runs, the shell tool copies the task’s durable inputs onto the sandbox filesystem at the same relative paths, so cat inputs/attachments/report.csv works.Files staged under a project prefix are materialized the same way at inputs/project/.

​
Verify

List what the task actually received:
Attachments appear under inputs/attachments/. To confirm they reached the sandbox disk rather than only durable storage, have the agent run ls -la inputs/attachments/ and check the event stream for the output — the file should be listed with its expected byte size.

​
Troubleshooting

The ref does not begin with staging/ . Only staged refs are accepted; a workspace path or an arbitrary object key is rejected. Re-stage with purpose=attachment or the presigned endpoint.
The staging object is not there — usually the presigned PUT was never completed, or it failed the checksum and the store discarded it. Confirm the upload returned 200 before creating the task.
The staged object has no recorded SHA-256, so the server cannot verify what it is copying. This happens when an object was placed in the staging prefix by something other than the two supported paths.
A single attachment is capped at 268435456 bytes (256 MiB). The task’s whole durable workspace is separately capped, so several large files can pass individually and still exceed the aggregate. See limits .
They do not collide — duplicate basenames are disambiguated deterministically, so a second report.csv becomes report-1.csv . Tell the agent to expect the suffixed name, or stage with distinct filenames.
Materialization happens once per shell session. If the sandbox pod was replaced mid-task, the inputs are not copied again, so the durable copy exists while the disk one does not. The file tool still reads them, because it falls back to durable storage on a miss; bash does not. Check whether the pod was reclaimed — see debug a failed task .

Run a command in a sandbox

Using the files

Collect artifacts and logs

Getting results back

Limits

Size ceilings

The file model

Why inputs are task-scoped

Artifacts

The durable store behind this
Last modified on September 17, 2026