---
title: Docker Sandbox
description: Create local persistent containers from an image or Dockerfile.
url: "https://eve.dev/docs/sandbox/docker"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Docker environments can use eve's default image, an existing OCI image, or `agent/sandbox/Dockerfile`.

```ts
import { defineSandbox } from "eve/sandbox";
import { DockerSandbox } from "eve/sandbox/docker";

export const environment = DockerSandbox.image("ghcr.io/acme/agent@sha256:...");

export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
```

## Choose the base image

`DockerSandbox.environment()`, `DockerSandbox.image()`, and `DockerSandbox.dockerfile()` all create the same Docker environment. They differ only in how you pass the base image:

| Constructor                                 | Base image without a Dockerfile          |
| ------------------------------------------- | ---------------------------------------- |
| `DockerSandbox.environment({ image })`      | `image`, or eve's default image if unset |
| `DockerSandbox.image("ghcr.io/acme/agent")` | The image reference you pass             |
| `DockerSandbox.dockerfile()`                | eve's default image                      |

When `agent/sandbox/Dockerfile` exists, eve builds it during preparation and uses the result as the base image for every constructor. The Dockerfile takes precedence over any `image` you pass, including `DockerSandbox.image(ref)`. eve uses the files under `agent/sandbox/` as the Docker build context. To use an existing image instead, remove the Dockerfile.

`DockerSandbox.dockerfile()` does not accept an `image` option, which makes the Dockerfile convention explicit in your sandbox file.

## Environment options

Image, pull policy, environment variables, and `prepare` belong to the reusable environment. During preparation, eve starts a temporary container, seeds workspace and skill files, runs your `prepare`, and commits the result as the recorded template image.

## Live container options

Pass `networkPolicy` to `open()`. Docker supports only `"allow-all"` and `"deny-all"`. The policy applies to the live container, not the prepared image.

A session-owned container keeps writable `/workspace` state in its container filesystem. A stopped container restarts with that state. `sandbox.delete()` removes the session's container by name and succeeds when the container is already gone.

See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)