Sessions & Filesystems - Hexel Studio

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

curl

curl -X POST https://api.hexelstudio.com/compute/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

string

Unique session identifier.

string

ISO 8601 creation timestamp.

Attach a filesystem

curl

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"}'

string

required

The filesystem to attach to this session.

Detach a filesystem

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 for the full session and filesystem operations.

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.

Is there a size limit on filesystems?

See the Tiers & Limits page for storage quotas per plan.

Limits & quotas

Limit	Scope	Behavior
Filesystem storage	Per filesystem	Plan-enforced; see Tiers & 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.

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.

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.

Sandboxes

On-demand execution environments.

Runtime Lifecycle

Leases and resource lifecycle.

Instances

Long-running deployments.

Compute Overview

The Compute model end to end.

Next steps

Continue to Runtime Lifecycle.

​Key ideas

​How it works

​States

​Create a session

​Attach a filesystem

​Detach a filesystem

​Limits & quotas

​Errors

​Security

​Common mistakes

​Best practices

​Related pages

Sandboxes

Runtime Lifecycle

Instances

Compute Overview

​Next steps

Key ideas

How it works

States

Create a session

Attach a filesystem

Detach a filesystem

Limits & quotas

Errors

Security

Common mistakes

Best practices

Related pages

Next steps