Skip to content

Images

Which container images a sandbox starts from, what it takes from the image, and image limits.

Updated View as Markdown

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

The 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 jobs

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

Navigation

Type to search…

↑↓ navigate↵ selectEsc close