Skip to main content
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 of an earlier sandbox, with --from <snapshot>; or
  • neither, which starts from the platform default image.
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:
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.
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 tracks the full list. See sandboxes for the current surface, resources for sizing, lifecycle for states and TTLs, and commands and executions for the exec and SSH contracts.