Workflow filesystem

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. The rule of thumb: if the workflow should remember it next time, put it in shared/. Everything else goes in workspace/.

​

What persists

shared/ is the durable region. Asteroid restores every saved shared file into the sandbox before the execution starts. Anything the workflow writes there syncs back to storage when the execution ends. The other three directories live and die with the execution. A new execution starts with them empty. This makes a workflow that improves over time. It can:

• Remember how a workflow works — save a step-by-step procedure so the next execution skips the trial and error.
• Record site-specific gotchas — a portal that needs a particular click order.
• Store and refine scripts — write a script during one execution, then reuse it on the next.
• Build up knowledge — accumulate extracted data, summaries and reference files.

​

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.

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: Each entry carries a downloadUrl. Call it with your API key and the server redirects you to the contents.

​

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.