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

# Sandboxes

> Isolated, single-use execution environments for code and commands.

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:

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/sandbox-lifecycle.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=e7a623bc8ac1e7058148f7d6e5264d8b" alt="Sandbox lifecycle" width="1774" height="887" data-path="assets/diagrams/sandbox-lifecycle.png" />

| 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

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    from hexel import Hexel

    client = Hexel(api_key="YOUR_API_KEY")
    sandbox = client.compute.sandbox.create(tier="standard")
    print(sandbox["sandbox_id"])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    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);
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    hexel compute sandbox create --tier standard
    ```
  </Tab>

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

### Request parameters

<ParamField path="tier" type="string" required>
  Compute tier: `micro`, `standard`, `large`, or `gpu`.
</ParamField>

<ParamField path="ttl_seconds" type="integer">
  Time-to-live in seconds. Defaults to `3600`.
</ParamField>

### Response

<ResponseField name="sandbox_id" type="string">Unique identifier for the allocated sandbox.</ResponseField>
<ResponseField name="state" type="string">Always `allocated` on success.</ResponseField>
<ResponseField name="endpoint" type="string">URL: `https://sandbox-<id>.compute.hexelstudio.com`</ResponseField>
<ResponseField name="tier" type="string">The tier allocated.</ResponseField>
<ResponseField name="expires_at" type="string">ISO 8601 timestamp when the sandbox will be terminated if not renewed.</ResponseField>

## Execute code

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    result = client.compute.sandbox.execute(
        sandbox["sandbox_id"],
        code="print(1 + 1)",
        language="python",
    )
    print(result)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    const result = await client.compute.sandbox.execute(sandbox.sandbox_id, {
      code: "print(1 + 1)",
      language: "python",
    });
    console.log(result);
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    hexel compute sandbox exec YOUR_SANDBOX_ID --code "print(1 + 1)"
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    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"}'
    ```
  </Tab>
</Tabs>

### Execute parameters

<ParamField path="code" type="string">
  Source code to execute. Provide either `code` or `command`, not both.
</ParamField>

<ParamField path="language" type="string">
  Language for the code (e.g., `python`). Required when `code` is provided.
</ParamField>

<ParamField path="command" type="string">
  Shell command to execute. Provide either `command` or `code`, not both.
</ParamField>

## Renew and release

```python theme={"dark"}
# 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

```python theme={"dark"}
# 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
```

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I reuse a released sandbox?">
    No. Sandboxes are single-use. After release or termination, allocate a new one.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How do I persist data across sandboxes?">
    Use a [filesystem](/docs/compute/sessions-and-filesystems) attached to a session. Sandbox-local storage is destroyed on termination.
  </Accordion>
</AccordionGroup>

## 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](https://console.hexelstudio.com).

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

<Tip>
  On `503`, back off and retry. The SDKs retry `503` automatically with exponential backoff.
</Tip>

## 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](/docs/compute/sessions-and-filesystems). |
| 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](/docs/compute/sessions-and-filesystems) 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](/docs/compute/sessions-and-filesystems) when you need state across sandboxes.

## Related pages

<CardGroup cols={2}>
  <Card title="Sessions & Filesystems" icon="folder-tree" href="/docs/compute/sessions-and-filesystems">
    Persist data across sandboxes.
  </Card>

  <Card title="Compute Overview" icon="microchip" href="/docs/compute/overview">
    Tiers and the compute model.
  </Card>

  <Card title="Agents" icon="robot" href="/docs/compute/agents">
    Long-running deployments instead of on-demand sandboxes.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/docs/getting-started/quickstart">
    Run your first sandbox.
  </Card>
</CardGroup>

## Next steps

Continue to [Agents](/docs/compute/agents) to deploy long-running workloads.