Skip to main content
Every sandbox starts from a base image: the reproducible environment that defines its initial filesystem, tools, dependencies, and runtime assumptions. Name one with --image, branch from a snapshot with --from, or name neither and start from the platform default image.

​
The platform default image

A create that names neither an image nor a snapshot starts from the platform default image, ghcr.io/hiloopai/sandbox-default: a general-purpose Debian base with Python 3.12 and Node 22 (plus npm) preinstalled, alongside the tools most work starts with, including git, gcc, g++, make, curl, wget, and an SSH client. So you can clone a repository and build it without installing anything first. It runs as root, so you can add whatever else the task needs with apt, pip, or npm once inside. rsync is not included. Use scp or sftp to move files, or apt-get install -y rsync inside the sandbox first.
The create receipt and hiloop sandbox get report the image that was selected, so you can pin it explicitly:
The default tracks a maintained base, so its contents advance over time. When reproducibility matters, pass an explicit digest-pinned --image instead of relying on the default.

​
Bring your own image

Use --image <reference> with any unmodified OCI image; digests and signatures stay intact. Two things to check:
  • Something has to keep running. A sandbox lives exactly as long as its first process. The sandbox runs the image’s own entrypoint, so an image whose entrypoint exits, such as a base OS image, fails to start and reports that its entrypoint exited. Give it a command to run instead.
  • Prefer digests over tags for long-running experiments, audits, and reproductions. The reference is human-readable; the digest is the immutable content identity.
Commands and shells start as the image’s own user in its WORKDIR.

​
Replacing the entrypoint

Pass a command after -- to run it as the sandbox’s first process instead of the image’s own entrypoint:
This replaces the entrypoint rather than wrapping it: your command is PID 1, with nothing of ours around it. Omit -- and the image’s ENTRYPOINT and CMD run exactly as they would anywhere else. The command is run directly, not through a shell, so pipes and redirection need an explicit shell:

​
What to include

Include stable, non-secret dependencies in the image:
  • operating system packages;
  • language runtimes;
  • pinned package managers;
  • common tools;
  • test runners;
  • browser or model runtime dependencies.
Keep secrets, per-run credentials, and mutable experiment state out of the image. A deployment without the complete proof-bound release path refuses a secret-bound create; an enabled path keeps the value outside the image and sandbox Pod.

​
Relationship to snapshots

Images are immutable starting baselines. A snapshot captures a sandbox’s disk state after work has happened, and hiloop sandbox create --from <snapshot> starts new sandboxes from that captured state, so branches share their history without rebuilding the image.

​
Restore onto a different image

A snapshot carries your workspace; the image is the runtime it is materialized onto. They are separate choices, so a create from a snapshot can name an image and land the same workspace on a newer base — a security patch or a toolchain bump without rebuilding what you have.
--storage-class durable is not decoration: a create from a snapshot needs a durable workspace and is refused without one. Omit --image and the restored sandbox runs the image its snapshot recorded. Either way, hiloop sandbox get reports what is actually running as workload_image — read that rather than inferring an image from lineage, because a restored sandbox does not necessarily run what its parent ran. The upgrade is a new sandbox, not an edit of the old one: the original keeps running until you verify the replacement and delete it. Nothing checks that the new image can use the old workspace, so keep the base compatible — a changed HOME, a different user id, or a language runtime your virtual environments were built against are all yours to reconcile. Naming an image without --from selects the source image of a fresh sandbox, as it always has.