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

# Sandboxes

> The sandbox model: one source per create, an explicit workspace, and a lifecycle you observe rather than assume.

A sandbox is an isolated environment for running commands or an agent. It has a durable product
identity: its id, name, lineage, and metadata outlive any individual runtime instance, and none of
them expose a Kubernetes pod, a container id, or a node name to the caller.

## Environment

A create names exactly one source:

* an unmodified OCI image, with `--image <ref>`;
* a [snapshot](/concepts/workspaces) of an earlier sandbox, with `--from <snapshot>`; or
* neither, which starts from the
  [platform default image](/sandboxes/images#the-platform-default-image).

```sh theme={null}
hiloop sandbox create build-box --image ghcr.io/acme/agent:2026-07-01
```

There is no named runtime profile to select. The image or snapshot you name is the environment.

## Workspace

Work belongs below `/workspace`; temporary state belongs below `/tmp`. What `/workspace` *is*
depends on the storage class chosen at create:

| Storage class        | `/workspace`                                                                                                                                 | Selected with                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `standard` (default) | An ordinary directory in the sandbox's own filesystem. Writes not captured by a snapshot are lost with the node.                             | nothing, or `--storage-class standard` |
| `durable`            | A deployment-backed workspace with its own lifetime, recovered from its configured backing storage and released when the sandbox is deleted. | `--storage-class durable`              |

```sh theme={null}
hiloop sandbox create trainer --storage-class durable
```

Your shell and your commands start in your image's working directory, which is not `/workspace`
unless your image says so: `cd` there, or set `WORKDIR` in your image.

## Lifecycle

1. Create the sandbox; the CLI waits until its observed state is running.
2. Run commands with `hiloop sandbox exec`, or open a shell with `hiloop sandbox ssh` where your
   deployment enables it.
3. Stop and start it. Files under `/workspace` survive on `durable` storage; processes do not
   resume, and the workload starts again from its image.
4. Delete the sandbox to release its runtime resources.

```sh theme={null}
hiloop sandbox exec build-box -- pytest -q
hiloop sandbox stop build-box
hiloop sandbox start build-box
hiloop sandbox delete build-box
```

Mutations are asynchronous: create, update, and delete return as soon as the request is accepted and
the observed state converges afterwards. What you read back is evidence of what the runtime is
doing, not a record of what was asked for.

## Admission fails closed

A request a deployment cannot serve exactly is refused at admission with a named
`unsupported_capability` error rather than quietly weakened. On the current sandbox runtime that
covers accelerator requests, volume mounts, and secret bindings.
[What's live today](/sandboxes/overview#whats-live-today) tracks the full list.

See [sandboxes](/sandboxes/overview) for the current surface,
[resources](/sandboxes/resources-capabilities) for sizing, [lifecycle](/sandboxes/lifecycle) for
states and TTLs, and [commands and executions](/sandboxes/commands-executions) for the exec and SSH
contracts.