---
title: "Images"
description: "Which container images a sandbox starts from, what it takes from the image, and image limits."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Images

A sandbox starts from a container image in [Container Registry](/registry), including images in a
[pull-through cache](/registry/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`.

```sh
docker pull --platform linux/amd64 <id>.registry.ezghcloud.com/docker-hub/library/python:3.13
```

## The image reference

```text
<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:

```json
"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](/sandboxes/commands). 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 `--`:

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

Source: https://docs.ezghcloud.com/sandboxes/images/index.mdx
