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

# Sandbox images

> Start from the platform default image, or bring any unmodified OCI image.

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.

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

The create receipt and `hiloop sandbox get` report the image that was selected, so you can pin
it explicitly:

```sh theme={null}
hiloop sandbox create quick-experiment --image ghcr.io/hiloopai/sandbox-default:latest
```

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:

```sh theme={null}
hiloop sandbox create dev --image ubuntu:24.04 -- sleep infinity
```

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:

```sh theme={null}
hiloop sandbox create dev --image ubuntu:24.04 -- bash -c 'setup.sh && sleep infinity'
```

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

```sh theme={null}
hiloop sandbox snapshot create devbox --name pre-upgrade --wait-remote
hiloop sandbox create devbox-v2 \
  --from pre-upgrade \
  --image ghcr.io/acme/base@sha256:9d3f1c... \
  --storage-class durable
```

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