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

# Run a sandbox

> Create a sandbox, run commands, snapshot it, and clean it up.

This guide walks the sandbox verbs: create from an image, inspect, execute, snapshot, branch, and
delete.

<Note>
  The runtime under these verbs is being rebuilt in stages. Create, list/get, TTL updates, and delete
  work end to end today, as do exec, stop/start, and snapshot and branch. `ssh` is complete, but it
  needs an endpoint that is off unless your deployment enables it. The authoritative status list is
  [what's live today](/sandboxes/overview#whats-live-today).
</Note>

## Create

```sh theme={null}
hiloop sandbox create experiment-a
```

Create accepts the request and the CLI waits until the sandbox is `running`. With no source flag,
the sandbox starts from the platform default image: a small general-purpose base with Python and
Node preinstalled. The receipt and JSON output report the image that was selected and the ambient
run id that receives this sandbox's telemetry.

To pick the source yourself, pass `--image <ref>` for a fresh environment or `--from <snapshot>`
to branch from saved state (pass both only to
[restore onto a different image](/sandboxes/images#restore-onto-a-different-image)):

```sh theme={null}
hiloop sandbox create experiment-a \
  --image ghcr.io/acme/research-agent@sha256:4f5c0f9a2e3d... \
  --cpus 0.05 \
  --memory-mb 128 \
  --ttl 7200 \
  --metadata team=research \
  --output json
```

Use a digest-pinned image when reproducibility matters, and pick an image whose entrypoint
keeps running: the sandbox runs the image's own entrypoint.

Compute resources are declarative: `--cpus` and `--memory-mb` set the shape the sandbox is
guaranteed, and CPU may burst into idle capacity beyond its request. `--cpus` accepts decimal
cores from `0.05` through `128`, with up to three fractional digits. Omitted values resolve to the
deployment's defaults at admission, and the resolved shape is echoed on every readout — the create
receipt, `get`, and `list` all show what was actually admitted, never a blank. JSON responses spell
CPU as exact integer `cpu_millis`; `50` means `0.05` CPU and `1000` means one CPU.

Automated callers that may retry an ambiguous create should pass a stable replay key:

```sh theme={null}
hiloop sandbox create experiment-a \
  --image ghcr.io/acme/research-agent@sha256:4f5c0f9a2e3d... \
  --idempotency-key build-42-attempt-1
```

Reusing the key replays the original accepted sandbox instead of creating a duplicate.

### Stop when idle

Give a sandbox an idle timeout when it should release compute after a quiet period:

```sh theme={null}
hiloop sandbox create experiment-a --storage-class durable --idle-timeout 1800
```

The timeout is measured in seconds and may be set from 60 through 86400. `sandbox get` shows both
the resolved timeout and, while the sandbox is running, its next idle deadline. Execs, SSH
sessions, and sandbox updates advance that deadline. Idle stop discards a `standard` workspace;
use `durable` storage when `/workspace` must survive the stop.

For a foreground command that may run longer than a buffered API request, run it through the managed
SSH session. The session keeps the sandbox active while the command lives and releases that hold
when it exits:

```sh theme={null}
hiloop sandbox ssh experiment-a -- python train.py --lr 3e-4
```

If the sandbox stops for idleness, `sandbox ssh` wakes it before opening the session. `sandbox exec`
does not wake a stopped sandbox and returns a stopped-state conflict, so start it explicitly before
the next buffered command. Apply any timeout, TTL, or metadata change while it is stopped, then
start it as a separate operation:

```sh theme={null}
hiloop sandbox update experiment-a --idle-timeout 3600
hiloop sandbox start experiment-a
```

Omit `--idle-timeout` to use the deployment default. The interactive hosted profile uses 1800
seconds when idle stopping is enabled; a self-hosted deployment may leave it disabled.

## Inspect

```sh theme={null}
hiloop sandbox get experiment-a
hiloop sandbox list --state running
hiloop sandbox list --metadata team=research
```

`get` shows the observed lifecycle state, the resolved compute shape, who created the sandbox,
expiry, and metadata. A sandbox created from a snapshot reads `from: <snapshot>` and resolves the
image it runs through that snapshot. `list` puts the compact resource shape and the creator in
the table, and filters by state, exact name, and exact metadata entries; pass `--all` to include
retained terminated records.

Every sandbox verb accepts either the server-issued id or the sandbox's name. A reference in
canonical id shape — `sbx-` followed by 40 lowercase hex characters — is always treated as an
id and addresses that sandbox directly; anything else is looked up as an exact name within the
selected project. Ids take precedence, so a name that happens to be minted in the id shape
cannot redirect an id-addressed command.

## Execute a command

```sh theme={null}
hiloop sandbox exec experiment-a --timeout 600 -- python train.py --lr 3e-4
```

`exec` submits one buffered command, relays its stdout/stderr, and exits with the command's exit
code. It also records that command's process lifecycle and output under the sandbox's ambient run;
no capture flag or guest credential is required. The full contract (timeouts, output caps, retries)
is in [commands and executions](/sandboxes/commands-executions).

Query the run id returned by create to inspect entrypoint, exec, SSH, cooperative HTTP, and OTLP
activity together:

```sh theme={null}
hiloop query --run-id "$RUN_ID" --limit 50
```

An explicit create command receives process and stdio supervision. An image's implicit entrypoint
still receives the shared HTTP proxy and OTLP settings, but its unknown command cannot be prepended
without changing the image contract. See [capture agent telemetry](/guides/capturing-telemetry#inside-a-sandbox)
for the exact boundaries.

## Connect a shell

```sh theme={null}
hiloop sandbox ssh experiment-a
```

`ssh` opens an interactive shell in a running sandbox using stock OpenSSH. There is nothing to set
up: the organization-scoped API credential you already use authorizes the connection, hiloop
supplies the session's key material, and the sandbox's host key is pinned for you, so you are never
prompted to accept an unknown host.

This verb needs the sandbox SSH endpoint, which an operator enables 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`.

Everything after `--` goes to `ssh`, options first and then an optional remote command:

```sh theme={null}
hiloop sandbox ssh experiment-a -- 'python -m pytest -q'
hiloop sandbox ssh experiment-a -- -tt tty
hiloop sandbox ssh experiment-a -- -L 8080:127.0.0.1:80 -N
```

A remote command's exit code becomes the CLI's exit code, and stdin and stdout pipe as usual.
Non-interactive commands are captured like buffered execs. Interactive PTY sessions record their
start, end, and terminal output, but not keystrokes/input.

The session runs inside your workload container, so it sees the same filesystem and processes that
`exec` does, and `-L` reaches a port your workload is listening on. Some SSH features are refused by
design, including remote port forwarding (`-R`), agent forwarding, and root login. Both points are
covered in [interactive access](/sandboxes/commands-executions#interactive-access); the connection
model is in [shell access](/concepts/architecture#shell-access).

## Snapshot and branch

Snapshot a sandbox's disk state, then create new sandboxes from the snapshot; restore, fork, and
branch are the same verb:

```sh theme={null}
hiloop sandbox snapshot create experiment-a --name baseline
hiloop sandbox create experiment-b --from baseline
hiloop sandbox create experiment-c --from baseline
```

Snapshots capture disk, not memory or processes. The model (durability receipts, lineage, and
fan-out) is covered in [snapshots and branching](/concepts/workspaces).

## Stop and start

```sh theme={null}
hiloop sandbox stop experiment-a
hiloop sandbox start experiment-a
```

Stop seals and stops the workload; start wakes it. A stopped sandbox keeps its identity, its name
and — on the `durable` storage class — its `/workspace`, which reattaches to the sandbox when it
starts again. Running processes do not survive a stop; the filesystem does. See
[lifecycle](/sandboxes/lifecycle#stop-and-start).

## Delete

```sh theme={null}
hiloop sandbox delete experiment-a
```

Delete is permanent and idempotent, and the CLI waits for termination. Snapshots are independent
resources: deleting a sandbox does not delete the snapshots taken from it.