> ## 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/`**    | Persists across all executions | 50 MB  | Durable memory — scripts, notes, extracted data, learned procedures      |
| **`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: 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](/concepts/executions). 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.

<Tip>
  Asteroid notifies the workflow when a new file appears in `downloads/` or `uploads/`. Changes to `shared/` and `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>