Skip to main content
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. 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.

​
Core resources

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 <name>: create from an OCI image (--image <ref>, 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.
  • hiloop sandbox list / get: observed state, endpoints, lineage, metadata.
  • TTL and metadata updates.
  • hiloop sandbox exec <name> -- <command>: 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 <snapshot>: 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 <name>: 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.
Deployment-gated sandbox attachments:

​
Start here