The Open Framework for Building Agents
---
title: "Docker Sandbox"
description: "Create local persistent containers from an image or Dockerfile."
---
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.