A sandbox starts from a container image in Container Registry, including images in a pull-through cache.
A pull-through cache image can be used once its linux/amd64 variant has been pulled through the
cache. Creating a sandbox doesn’t fetch it from Docker Hub: until it has been pulled, the answer is
400 image_not_found.
docker pull --platform linux/amd64 <id>.registry.ezghcloud.com/docker-hub/library/python:3.13The image reference
<registry host>/<repository>[:<tag>|@<digest>]For example <id>.registry.ezghcloud.com/team-a/runner:v3, or the same repository with
@sha256:…. The image must have a linux/amd64 variant.
Permission to pull
Whoever creates the sandbox needs permission to pull the image. It’s checked when the sandbox is created:
| Answer | Means |
|---|---|
400 image_not_found |
There’s no such image, or it’s a pull-through cache image that hasn’t been pulled yet. |
403 image_access_denied |
You can’t pull it. |
The digest is fixed at create
A tag is resolved to a digest when the sandbox is created, and every later start of that sandbox uses that digest. Moving the tag afterwards doesn’t change a sandbox that already exists. The sandbox shows what was asked for and what it resolved to:
"image": {
"reference": "<id>.registry.ezghcloud.com/team-a/runner:v3",
"repository": "<id>.registry.ezghcloud.com/team-a/runner",
"digest": "sha256:…"
}What a sandbox takes from the image
- Its files are the sandbox’s disk as it starts. Changes are kept on the sandbox’s own disk and never change the image.
- Its environment, working directory and user are the defaults for every command. A command can set its own.
- Its entrypoint and command don’t run. A sandbox starts and waits for your commands.
A start command
command at create runs when the sandbox starts. It’s at most 64 arguments and 8 KiB in all. Its output isn’t returned: write it to a file to read it later. With the CLI it follows --:
ezgh sandboxes create "$IMAGE" -- /usr/local/bin/worker --queue jobsenv at create sets the sandbox’s environment variables: at most 64, 32 KiB in all. The API returns the variables’ names
(envNames) and whether there’s a start command (hasCommand), never the values or the command.
Limits
| Limit | |
|---|---|
| Image size, unpacked | 20 GiB |
| Files and directories | 1,000,000 |
| Layers | 127 |
The first sandbox from a new image
An image is prepared the first time a sandbox starts from it, which takes longer the larger it is.
Create waits up to 10 seconds, so the first create from a new image may answer starting: wait
for running (--wait in the CLI). Later sandboxes from
the same digest start without that step.