Workflow filesystem

The directory layout inside an execution, what survives between runs, the quotas, and how files get in and out.

Every workflow has a real filesystem. During an execution the workflow creates files, edits them and runs scripts, like a developer on a laptop.

The workflow uses standard tools for this: Read, Write, Edit, Glob, Grep and Bash. The working directory is /home/agent.

Directory layout

Each execution mounts a filesystem under /home/agent. Four directories are yours to work with.

Directory	Scope	Quota	Purpose
shared/	Seeded from the workflow, read at run time	50 MB	The workflow’s own files: node scripts, plus libraries and reference data they read
workspace/	Current execution only	500 MB	Scratch space for in-progress work
downloads/	Current execution only	500 MB	Browser downloads land here (see Environments)
uploads/	Current execution only	200 MB	Files attached via API or staging

The rule of thumb: shared/ holds the files the workflow was built with and reads at run time. Put a run’s scratch work in workspace/; browser downloads land in downloads/.

What persists

shared/ holds the files the workflow was built with. Asteroid restores them into the sandbox before the execution starts, so the node scripts and the data they read are always present.

A running execution’s own writes are not durable. Nothing written to the sandbox during a run carries into the next run. Keep per-run state in workspace/. Files in downloads/ still sync to the execution’s Files area for that run, but a new execution starts with workspace/, downloads/ and uploads/ empty, and shared/ holding the workflow’s files again.

Durable shared/ content comes from how the workflow is built. Astro writes scripts and reference files there when it builds or edits the workflow, and those persist for every later run. Use shared/ for:

• Reference data a script reads — a field map, a bundled library, a lookup table.
• The node scripts themselves — each lives under shared/<node-slug>/.
• Site-specific gotchas captured at build time — a portal that needs a particular click order.

Asteroid notifies the workflow when a new file appears in downloads/ or uploads/. Writes to workspace/ raise no notification, because the workflow wrote those files itself.

File types the workflow can read

• Images (PNG, JPEG)
• PDFs
• Text files (TXT, MD)
• CSVs

Getting files in

There are two paths, and the difference is timing.

Before the execution starts

Stage the files first, then pass them to the execute call.

1. POST /temp-files/{organizationId} returns a tempFiles array. Each entry has an id and a name.
2. Pass that array as tempFiles on POST /agents/{agentId}/execute.
3. The execution starts with the files attached to its context.

A staged file expires after 60 minutes. Start the execution inside that window, or Asteroid deletes the file.

Call a workflow from your code has the working staging call.

While the execution is going

Upload straight to the running execution instead. The files appear in the execution context and the workflow is notified.

Getting files out

Files the workflow downloads land in /home/agent/downloads, and sync like every other workflow directory. They appear in the Files area of the execution and in the file listings.

Two endpoints list the files on an execution:

Endpoint	Returns
GET /executions/{executionId}/files	Every file the execution produced, grouped by directory
GET /executions/{executionId}/context-files	Files attached to the execution context

Each entry carries a downloadUrl. Call it with your API key and the server redirects you to the contents.

downloadUrl is an authenticated Asteroid URL, not a direct storage link. Your HTTP client follows the redirect for you.

Uploading files to a website

The workflow uses the Upload File tool to put a file into a web form. It accepts a local file, or a file it downloaded earlier, addressed as downloads/filename.

Call a workflow

Stage files and read them back

Environments

Where the sandbox comes from