Files are documents the agent can read during a run, such as instructions, reference data or examples. You upload them once to your organization and choose, for each run or workflow, which ones to mount and where.
Uploading files
Upload files in the dashboard under Files, with POST /v1/files, or with ephemeral files upload. Each file gets an ID such as file_9c41… and a name. The name is a relative path like guides/refunds.md, up to 240 characters.
Uploading again with a name that already exists adds a new file with a new ID. The file list shows the latest upload for each name. Older uploads stay available by ID until you delete them.
Giving files to a run
List the files in the run's files array. Each entry mounts one file at a path of your choice. There are three ways to name the content:
| Entry | Mounts |
|---|---|
{"file": "file_ | That exact upload. |
{"file": "guides/ | The latest upload with that name, at the time the run is created. |
{"path": "notes. | Inline text sent with the request. Nothing is uploaded. |
For uploaded files, path defaults to the file's name. Inline files must set it. Paths must be relative and unique within the run.
"files": [
{ "file": "guides/refunds.md", "path": "instructions/refunds.md" },
{ "file": "file_9c41d2a07be35f1e8a6c0d4b9e2f7a13" },
{ "path": "context.md", "content": "The customer is on the annual plan." }
]Inside the microVM
The worker receives the files as a read-only directory and is told the path of each one. It cannot change them. Its working directory is a separate scratch area. Anything it writes there disappears when the microVM is destroyed, so files are never shared between runs. The run's result is its text output.
A run reads file contents when it leaves the queue. If you delete a file while a run that uses it is still queued, that run fails.
Limits
| Limit | Value |
|---|---|
| File size | 1 MiB per file, uploaded or inline |
| Files per run | 32 |
| Total per run | 4 MiB |
See the Files API for upload, download, rename and delete.