> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/concepts/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](/build/in-the-platform) 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.

<Tip>
  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.
</Tip>

## 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.

```mermaid theme={null}
sequenceDiagram
    participant App
    participant StagingAPI as /temp-files
    participant ExecuteAPI as /agents/{id}/execute
    participant Execution

    App->>StagingAPI: POST files
    StagingAPI-->>App: tempFiles (id, name)
    Note over App: Must use within 60 mins
    App->>ExecuteAPI: POST with tempFiles array
    ExecuteAPI->>Execution: Start with files attached
```

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.

<Warning>
  A staged file expires after **60 minutes**. Start the execution inside that window, or Asteroid deletes the file.
</Warning>

[Call a workflow from your code](/integrate/call-an-agent) 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.

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

## 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`.

<CardGroup cols={2}>
  <Card title="Call a workflow" icon="code" href="/integrate/call-an-agent">Stage files and read them back</Card>
  <Card title="Environments" icon="monitor" href="/concepts/environments">Where the sandbox comes from</Card>
</CardGroup>