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

# Sessions & Filesystems

> Group runtime resources and attach persistent storage to workloads.

Sometimes your workload needs to keep state between calls — an agent builds a file mid-task, or a workflow spans multiple sandbox invocations that each need access to the same data. That's when sessions and filesystems come in.

Sessions group related runtime resources so they can be managed together. Filesystems provide persistent storage you can attach to a session, letting stateful workloads keep data across calls.

## Key ideas

| Term           | Meaning                                                                  |
| -------------- | ------------------------------------------------------------------------ |
| **Session**    | A logical grouping of runtime resources managed as a unit.               |
| **Filesystem** | Persistent storage that can be attached to a session.                    |
| **Attach**     | Connecting a filesystem to a session so workloads can read and write it. |

## How it works

```
Create session → Create/reuse filesystem → Attach → Read/write → Detach → Delete
```

Workloads in a session read and write the attached filesystem. Data persists across sandbox allocations and instance restarts within the same session.

## States

| Resource   | States                          |
| ---------- | ------------------------------- |
| Session    | `starting`, `running`           |
| Filesystem | `creating`, `ready`, `deleting` |

A filesystem must be `ready` before it can be attached.

## Create a session

<Tabs>
  <Tab title="curl">
    ```bash theme={"dark"}
    curl -X POST https://api.hexelstudio.com/compute/v1/sessions \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Tab>
</Tabs>

<ResponseField name="session_id" type="string">Unique session identifier.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>

## Attach a filesystem

<Tabs>
  <Tab title="curl">
    ```bash theme={"dark"}
    curl -X POST https://api.hexelstudio.com/compute/v1/sessions/YOUR_SESSION_ID/filesystems \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"filesystem_id": "YOUR_FILESYSTEM_ID"}'
    ```
  </Tab>
</Tabs>

<ParamField path="filesystem_id" type="string" required>
  The filesystem to attach to this session.
</ParamField>

## Detach a filesystem

```bash theme={"dark"}
curl -X DELETE https://api.hexelstudio.com/compute/v1/sessions/YOUR_SESSION_ID/filesystems/YOUR_FILESYSTEM_ID \
  -H "Authorization: Bearer $TOKEN"
```

See the [API Reference](/docs/api-reference/introduction) for the full session and filesystem operations.

<AccordionGroup>
  <Accordion title="What happens to data when a sandbox terminates?">
    Sandbox-local storage is destroyed. Data written to an attached filesystem persists independently of the sandbox lifecycle.
  </Accordion>

  <Accordion title="Can multiple workloads share a filesystem?">
    Yes, but scope filesystems to related workloads for isolation. Concurrent writes from unrelated processes can cause conflicts.
  </Accordion>

  <Accordion title="Is there a size limit on filesystems?">
    See the [Tiers & Limits](/docs/billing/tiers-and-limits) page for storage quotas per plan.
  </Accordion>
</AccordionGroup>

## Limits & quotas

| Limit                  | Scope            | Behavior                                                        |
| ---------------------- | ---------------- | --------------------------------------------------------------- |
| Filesystem storage     | Per filesystem   | Plan-enforced; see [Tiers & Limits](/docs/billing/tiers-and-limits). |
| Sessions / filesystems | Per organization | Plan-enforced.                                                  |

## Errors

| `error_code`        | HTTP | When                                       |
| ------------------- | ---- | ------------------------------------------ |
| `session_not_found` | 404  | The session ID doesn't exist.              |
| `not_found`         | 404  | The filesystem ID doesn't exist.           |
| `invalid_request`   | 400  | Attaching a filesystem that isn't `ready`. |

## Security

| Concern        | Detail                                                                                |
| -------------- | ------------------------------------------------------------------------------------- |
| Access         | A filesystem is only reachable by workloads in a session you explicitly attach it to. |
| Data retention | Data persists until you delete the filesystem. It does not expire with the session.   |
| Scoping        | Filesystems are scoped to your organization, workspace, and environment.              |

<Tip>
  Scope each filesystem to the specific workloads that need it. Attaching a filesystem to a broad session gives all workloads in that session read/write access.
</Tip>

## Common mistakes

* **Assuming sandbox storage is permanent.** A released sandbox's local storage is gone; use a filesystem for data that must survive.
* **Sharing one filesystem across unrelated workloads.** Scope filesystems to the work that needs them.

## Best practices

* Attach a filesystem only for the lifetime you need it, then detach.
* Keep filesystems scoped to a single workload or session for isolation.
* Delete unused sessions and filesystems to free storage.

## Related pages

<CardGroup cols={2}>
  <Card title="Sandboxes" icon="terminal" href="/docs/compute/sandboxes">
    On-demand execution environments.
  </Card>

  <Card title="Runtime Lifecycle" icon="arrows-rotate" href="/docs/compute/runtime-lifecycle">
    Leases and resource lifecycle.
  </Card>

  <Card title="Instances" icon="server" href="/docs/compute/instances">
    Long-running deployments.
  </Card>

  <Card title="Compute Overview" icon="microchip" href="/docs/compute/overview">
    The Compute model end to end.
  </Card>
</CardGroup>

## Next steps

Continue to [Runtime Lifecycle](/docs/compute/runtime-lifecycle).