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

# Run Docker in a Celesto sandbox

> Run Docker in a Celesto sandbox to test apps in a separate environment. Install Docker, run a container locally or in the cloud, and automate setup in Python.

You can run apps and test your projects with Docker inside a Celesto sandbox. Your tools and files stay in the sandbox, giving you a separate place to try changes.

Docker packages an app and the software it needs into a **Docker image**. A **container** is a running copy of a Docker image. You install Docker inside the sandbox, then use its commands there.

## Before you start

* Install the [Celesto command-line tool](/docs/smolvm/installation.md). For cloud computers, also [sign in](/docs/cloud/cli.md#install-and-sign-in).
* Use a fresh Ubuntu sandbox with the current Celesto software and image. Celesto starts Docker's background service automatically after you install it.
* Allow internet access to Ubuntu package servers and Docker Hub, the service that stores the example images.
* Give Docker room for package downloads and images. For the local example, start with 2048 MiB of memory and 4096 MiB of disk space. MiB is a unit of memory and storage size. For cloud computers, use [Standard size](/docs/cloud/features/resources.md#choose-a-named-size) or larger.

## Install Docker and run a container

**1. Open your sandbox**

Run the commands in the tab for your setup on your own machine.

**Local sandbox**

Create an Ubuntu sandbox named `docker-demo` and open its terminal:

```bash theme={null}
celesto sandbox create --name docker-demo --os ubuntu --memory 2048 --disk-size 4096
celesto sandbox shell docker-demo
```

The terminal runs inside your sandbox as `root`, the user with permission to install software.

**Cloud computer**

Create a Standard computer, which includes a 30 GB disk with space for Docker images:

```bash theme={null}
celesto computer create --template coding-agent --cpus 2 --memory 4096
```

Copy the computer name from the output. Run the following command, replacing `einstein` with that name:

```bash theme={null}
celesto computer ssh einstein
```

Inside the computer, open a shell with permission to install software:

```bash theme={null}
sudo -i
```

Run the remaining commands in this section inside the sandbox.

**2. Install Docker**

Download the package list, then install Docker and its network tools:

```bash theme={null}
apt-get update -o APT::Update::Error-Mode=any && \
  DEBIAN_FRONTEND=noninteractive apt-get install -y docker.io iptables
```

Wait for the installation to finish successfully. Celesto detects Docker and starts its **daemon**, the background service that runs containers.

**3. Wait for Docker to be ready**

This check waits up to two minutes. If startup fails, it prints the Docker log to help you find the cause.

```bash theme={null}
sh -eu <<'SH'
for attempt in $(seq 1 60); do
  if docker info >/dev/null 2>&1; then
    echo "Docker is ready"
    exit 0
  fi
  sleep 2
done
echo "Docker did not become ready. Check the log below." >&2
tail -n 80 /var/log/celesto-docker.log >&2 || true
exit 1
SH
```

Continue when you see `Docker is ready`.

**4. Run your first container**

Download and run Docker's small verification image:

```bash theme={null}
docker run --rm hello-world
```

> [!TIP]
>
> The output includes `Hello from Docker!`. This confirms Docker can download an image and run a container inside your sandbox.

The `--rm` flag removes the container after it finishes. Docker keeps the downloaded image so you can reuse it. See Docker's [guide to running containers](https://docs.docker.com/engine/containers/run/) for more options.

## Run Docker from Python

Use the Python SDK (software development kit) to create a local Ubuntu sandbox, install Docker, and run a container from your program. Run this script on your own machine after completing [Celesto installation](/docs/smolvm/installation.md).

Save it as `docker_demo.py`:

```python docker_demo.py theme={null}
from celesto import Celesto


def run_checked(sandbox, command, timeout):
    result = sandbox.run(command, timeout=timeout)
    if result.exit_code != 0:
        raise RuntimeError(
            f"Command failed: {command}\n{result.stdout}\n{result.stderr}"
        )
    return result.stdout


with Celesto(os="ubuntu", memory=2048, disk_size=4096) as sandbox:
    run_checked(
        sandbox,
        "apt-get update -qq -o APT::Update::Error-Mode=any && "
        "DEBIAN_FRONTEND=noninteractive apt-get install -y -qq docker.io iptables",
        timeout=600,
    )
    run_checked(
        sandbox,
        "for attempt in $(seq 1 60); do "
        "if docker info >/dev/null 2>&1; then exit 0; fi; "
        "sleep 2; done; "
        "tail -n 80 /var/log/celesto-docker.log >&2 || true; exit 1",
        timeout=180,
    )
    print(run_checked(sandbox, "docker run --rm hello-world", timeout=180))
```

Run the script:

```bash theme={null}
python docker_demo.py
```

The output includes `Hello from Docker!`. The script checks each command's exit code and gives package installation and image downloads extra time to finish.

## Troubleshoot Docker in a Celesto sandbox

Run these checks inside the sandbox with the same permissions you used during installation.

> **Docker cannot connect to its background service**
>
> Run the readiness check again, then read the startup log:
>
> ```bash theme={null}
> tail -n 80 /var/log/celesto-docker.log
> ```
>
> Celesto manages the service through its guest agent, a small program inside the sandbox. Use a fresh Ubuntu sandbox with the current image if an older sandbox has no Docker startup log. The setup above uses Celesto's service management rather than `systemctl`.

> **Package installation or image downloads fail**
>
> Check whether the sandbox can find the package server and Docker Hub:
>
> ```bash theme={null}
> getent ahostsv4 archive.ubuntu.com
> getent ahostsv4 registry-1.docker.io
> ```
>
> Each command should print IP addresses. If a lookup fails, check internet access and outbound network rules for your [local sandbox](/docs/smolvm/features/network-controls.md) or [cloud computer](/docs/cloud/features/network-control.md). Then retry the failed installation or download command.

> **Docker runs out of disk space or memory**
>
> Check available disk space and Docker's storage use:
>
> ```bash theme={null}
> df -h /
> docker system df
> ```
>
> Create a larger sandbox when your Docker images or builds need more space. For cloud computers, [compare computer sizes](/docs/cloud/features/resources.md). Increase memory when programs run out of memory. Docker images and containers use the sandbox's own resources.

## Next steps

* [Forward a local sandbox port](/docs/smolvm/features/port-forwarding.md) to reach a container's web app from your machine. Publish the container port to the sandbox with Docker's `-p` flag first.
* [Publish a cloud computer port](/docs/cloud/features/publish-ports.md) to give a container's web app an HTTPS address.
* [Build custom sandbox images](/docs/smolvm/guides/custom-images.md) when you want to choose the tools available when a sandbox starts.
* [Build a Celesto Cloud custom template](/docs/cloud/features/custom-templates.md) to start every cloud computer with your packages preinstalled.


## Related topics

- [Custom Sandbox Images with Docker](/docs/smolvm/guides/custom-images.md)
- [Docker and services](/docs/ci/docker.md)
- [DockerRootfsBuilder](/docs/smolvm/api/dockerrootfsbuilder.md)
- [GitHub Actions runners](/docs/ci.md)
- [Troubleshooting guide](/docs/smolvm/advanced/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.