Sandboxes - Hexel Studio

A sandbox is an isolated execution environment you allocate on demand to run code, shell commands, and file operations. Sandboxes are drawn from a warm pool, so allocation is fast, and each one is single-use — released sandboxes are not recycled.

Lifecycle

Use sandboxes when your agent needs to execute user-provided code, run a data transformation step, call a shell tool, or do any work that should be isolated and disposable. Common examples: an LLM agent that writes and runs Python to answer a data question, a CI tool that tests generated code, or a pipeline step that processes a file and discards the environment afterward. A sandbox moves through three states:

State	Meaning
`warm`	Pre-warmed in the pool, ready to be allocated.
`allocated`	Assigned to you and running your work.
`terminated`	Released, expired, or failed. Not reused.

Allocated sandboxes have a default TTL of 3600 seconds (1 hour). Extend it with renew, or release the sandbox when done.

SDK methods

Method	Description
`client.compute.sandbox.create()`	Allocate a sandbox. Returns `sandbox_id`.
`client.compute.sandbox.list()`	List your sandboxes.
`client.compute.sandbox.get(id)`	Get sandbox details and state.
`client.compute.sandbox.execute(id, ...)`	Execute code or a command in the sandbox.
`client.compute.sandbox.renew(id, ...)`	Extend TTL on an allocated sandbox.
`client.compute.sandbox.release(id)`	Terminate the sandbox.
`client.compute.sandbox.delete(id)`	Delete sandbox record.

Allocate a sandbox

Python
TypeScript
CLI
curl

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")
sandbox = client.compute.sandbox.create(tier="standard")
print(sandbox["sandbox_id"])

import { Hexel } from "hexel-sdk";

const client = new Hexel({ apiKey: "YOUR_API_KEY" });
const sandbox = await client.compute.sandbox.create({ tier: "standard" });
console.log(sandbox.sandbox_id);

hexel compute sandbox create --tier standard

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

Request parameters

string

required

Compute tier: micro, standard, large, or gpu.

integer

Time-to-live in seconds. Defaults to 3600.

Response

string

Unique identifier for the allocated sandbox.

string

Always allocated on success.

string

URL: https://sandbox-<id>.compute.hexelstudio.com

string

The tier allocated.

string

ISO 8601 timestamp when the sandbox will be terminated if not renewed.

Execute code

Python
TypeScript
CLI
curl

result = client.compute.sandbox.execute(
    sandbox["sandbox_id"],
    code="print(1 + 1)",
    language="python",
)
print(result)

const result = await client.compute.sandbox.execute(sandbox.sandbox_id, {
  code: "print(1 + 1)",
  language: "python",
});
console.log(result);

hexel compute sandbox exec YOUR_SANDBOX_ID --code "print(1 + 1)"

curl -X POST https://api.hexelstudio.com/compute/v1/sandboxes/YOUR_SANDBOX_ID/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "print(1 + 1)", "language": "python"}'

Execute parameters

string

Source code to execute. Provide either code or command, not both.

string

Language for the code (e.g., python). Required when code is provided.

string

Shell command to execute. Provide either command or code, not both.

Renew and release

# Extend the TTL on a running sandbox
client.compute.sandbox.renew(sandbox["sandbox_id"], ttl_seconds=3600)

# Release when done — terminates the sandbox
client.compute.sandbox.release(sandbox["sandbox_id"])

List and get

# List all your sandboxes
sandboxes = client.compute.sandbox.list()

# Get details for one sandbox
details = client.compute.sandbox.get("YOUR_SANDBOX_ID")
print(details["state"])  # warm | allocated | terminated

Reach a running sandbox

An allocated sandbox is reachable at:

https://sandbox-YOUR_SANDBOX_ID.compute.hexelstudio.com

What happens when the TTL expires?

The sandbox transitions to terminated. Any running process is killed and local storage is destroyed. Extend the TTL with renew before expiry if you need more time.

Can I reuse a released sandbox?

No. Sandboxes are single-use. After release or termination, allocate a new one.

What if the requested tier is unavailable?

The allocation returns HTTP 503. There is no automatic fallback to another tier. Retry after a short delay or request a different tier.

How do I persist data across sandboxes?

Use a filesystem attached to a session. Sandbox-local storage is destroyed on termination.

Limits & quotas

Limit	Scope	Behavior
Concurrent sandboxes	Per organization	Plan-enforced. Allocating beyond it returns `429 quota_exceeded`.
TTL	Per sandbox	Default 3600s; extend with `renew`.

Numeric limits depend on your plan — see the Console.

Errors

`error_code`	HTTP	When
`invalid_request`	400	Both `code` and `command` supplied, or missing `tier`.
`vm_not_found`	404	The sandbox ID doesn’t exist or was terminated.
`quota_exceeded`	429	Concurrent-sandbox quota reached.
`vm_unavailable`	503	No sandboxes available for the tier. Retry shortly.
`capacity_exhausted`	503	No warm capacity; a `Retry-After` header is returned.

On 503, back off and retry. The SDKs retry 503 automatically with exponential backoff.

Security

Concern	Detail
Isolation	Each sandbox is isolated and single-use. It is never shared between workloads and never reused after release.
Storage	Local sandbox storage is destroyed on termination. Keep durable data in a filesystem.
Scoping	All access is scoped to your organization, workspace, and environment.

Common mistakes

Reusing a released sandbox. Released sandboxes are terminated; allocate a new one.
Letting work outlive the TTL. Renew before the 1-hour default expires, or the sandbox terminates mid-execution.
Storing data you need to keep in a sandbox. Local storage is lost on termination — use a filesystem for persistence.

Best practices

Release sandboxes as soon as you’re done to free capacity.
Pick the smallest tier that fits the workload.
Use a persistent session with a filesystem when you need state across sandboxes.

Sessions & Filesystems

Persist data across sandboxes.

Compute Overview

Tiers and the compute model.

Agents

Long-running deployments instead of on-demand sandboxes.

Quickstart

Run your first sandbox.

Next steps

Continue to Agents to deploy long-running workloads.

​Lifecycle

​SDK methods

​Allocate a sandbox

​Request parameters

​Response

​Execute code

​Execute parameters

​Renew and release

​List and get

​Reach a running sandbox

​Limits & quotas

​Errors

​Security

​Common mistakes

​Best practices

​Related pages

Sessions & Filesystems

Compute Overview

Agents

Quickstart

​Next steps

Lifecycle

SDK methods

Allocate a sandbox

Request parameters

Response

Execute code

Execute parameters

Renew and release

List and get

Reach a running sandbox

Limits & quotas

Errors

Security

Common mistakes

Best practices

Related pages

Next steps