> ## 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 > Isolated environments created from an OCI image or a snapshot, with snapshots and branching as first-class verbs. Use a sandbox to run commands or an agent in an isolated environment. Every sandbox starts from one of two sources: an unmodified OCI image, or a **snapshot** of an earlier sandbox. Name at most one; a create that names neither starts from the [platform default image](/sandboxes/images#the-platform-default-image). Creating from a snapshot is restore, fork, and branch in one verb: several sandboxes can start from the same snapshot and diverge, and the lineage between them is recorded. A create from a snapshot may also name an image, which is how a workspace moves to a newer base without being rebuilt: see [restore onto a different image](/sandboxes/images#restore-onto-a-different-image). ```mermaid theme={null} flowchart LR I[OCI image] --> A[Sandbox] A --> P[Snapshot] P --> B[Sandbox branch 1] P --> C[Sandbox branch 2] ``` ## Core resources | Resource | What it represents | | -------------- | ---------------------------------------------------------------------------------------------- | | Sandbox | An isolated environment with an observed lifecycle state, TTL, metadata, and recorded lineage. | | Snapshot | An immutable capture of a sandbox's disk state, usable as the source for new sandboxes. | | Volume | Immutable, versioned data published once and mounted by many sandboxes. | | Secret binding | A pre-registered credential named at create so the platform, not your code, handles the value. | The API is nine routes over two resources, sandboxes and snapshots, plus the volume and secret registries. Mutations are asynchronous: create, update, and delete return immediately and you poll the sandbox until its observed state reaches the outcome you asked for (the CLI waits for you). ## What's live today The runtime under this API is being rebuilt in stages. Finished stages work end to end; unfinished stages **fail closed with explicit errors**: a request is refused rather than silently weakened. Working end to end now: * `hiloop sandbox create `: create from an OCI image (`--image `, or the platform default image when omitted) and wait until running. * `hiloop sandbox create --storage-class durable`: mounts `/workspace` as a volume with its own lifetime, released when the sandbox is deleted. Files written there survive losing the sandbox's node; running processes do not, and the workload starts again from its image on the replacement. Available by default; a deployment whose cluster names no backing storage class refuses the request with `unsupported_capability` rather than downgrading to node-bound storage. On the platform default image `/workspace` is also your home directory, so a tool you install and the configuration it writes are kept alongside your files. A custom image keeps whatever `HOME` and `WORKDIR` it sets; point them under `/workspace` if you want the same. See [durability](/sandboxes/reliability#what-is-durable-today). * `hiloop sandbox list` / `get`: observed state, endpoints, lineage, metadata. * TTL and metadata updates. * `hiloop sandbox exec -- `: one buffered command in the workload container, with its real exit code, separated stdout and stderr, and replay-safe retries. * `hiloop sandbox stop` / `hiloop sandbox start`: stop seals and stops the workload, start wakes it. The sandbox keeps its identity and its name across a stop, and on `durable` storage its `/workspace` is recovered from the configured backing storage. Running processes do not survive a stop; files under `/workspace` do. * `hiloop sandbox delete`: permanent, idempotent teardown. * `hiloop sandbox snapshot create` / `snapshot list`: capture a durable sandbox's workspace and list what you have captured. A completed snapshot reports its durability. * `hiloop sandbox create --from `: start a new sandbox on a snapshot's workspace. Several can start from one snapshot and diverge; the lineage between them is recorded. A `--from` naming a snapshot that never reached durability is refused with `snapshot_not_restorable`. Built and working, but off unless your deployment enables it: * `hiloop sandbox ssh `: an interactive shell, remote commands, and `-L` port forwarding over stock OpenSSH. The shell runs inside your workload container, so it sees your image's filesystem as the image's own user, starting in its `WORKDIR`. This one verb depends on the sandbox SSH endpoint, which an operator turns on per deployment and which is off by default; on the hosted service it is currently enabled only in pre-release environments. Where it is off, a connect is refused with `unsupported_capability` and nothing else about the sandbox changes. See [interactive access](/sandboxes/commands-executions#interactive-access). Deployment-gated sandbox attachments: | Verb | Today | | ---------- | --------------------------------------------------------------------------------------------- | | `--secret` | Available on the hosted service for a bearer secret bound to one exact public HTTPS hostname. | | `--volume` | Refused at admission with `unsupported_capability` naming the missing transport. | ## Start here * [Quickstart](/guides/quickstart) for install, sign-in, and a first sandbox. * [Run a sandbox](/guides/running-sandboxes) for the create, execute, and clean-up flow. * [Lifecycle](/sandboxes/lifecycle) for states, asynchronous mutations, and TTLs. * [Snapshots and branching](/concepts/workspaces) for the persistence and fan-out model. * [Commands and executions](/sandboxes/commands-executions) for the exec contract and the SSH session contract. * [Network access](/sandboxes/network-egress) for the outbound-network posture.