---
title: Default Sandbox
description: Let eve select the sandbox provider when it prepares the sandbox.
url: "https://eve.dev/docs/sandbox/default"
docs_index: /llms.txt
---

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

`DefaultSandbox.environment()` selects a sandbox provider when eve prepares the sandbox, records the choice, and uses that provider for every session the build serves.

```ts
import { DefaultSandbox, defineSandbox } from "eve/sandbox";

export const environment = DefaultSandbox.environment();
export default defineSandbox(() => environment.open());
```

On Vercel, it selects [Vercel Sandbox](/docs/sandbox/vercel). Elsewhere, it selects [Docker](/docs/sandbox/docker) when a Docker daemon is reachable, and [just-bash](/docs/sandbox/just-bash) only during `eve dev` and `eve eval`.

## How eve selects the provider

eve selects the provider when it prepares the sandbox: during `eve build`, or during `eve dev` the first time a session opens the sandbox. It checks in this order:

1. If the `VERCEL` environment variable is set, it selects Vercel.
2. Otherwise, if `docker version` reports a running Linux Docker daemon within five seconds, it selects Docker.
3. Otherwise, during `eve dev` and `eve eval`, it selects just-bash.
4. Otherwise, in a production `eve build`, it selects no provider.

| Where eve prepares the sandbox                    | Selected provider                             |
| ------------------------------------------------- | --------------------------------------------- |
| On Vercel (`vercel build` or a Vercel deploy)     | [Vercel Sandbox](/docs/sandbox/vercel)        |
| Anywhere a Linux Docker daemon is reachable       | [Docker](/docs/sandbox/docker)                |
| `eve dev` or `eve eval` without Docker            | [just-bash](/docs/sandbox/just-bash)          |
| A production `eve build` without Vercel or Docker | None: opening the sandbox fails with an error |

Production builds never fall back to just-bash, because just-bash runs no native processes and provides no network isolation. When no provider is available, `eve build` still succeeds and logs that no provider is available. The first session that opens the sandbox fails with an error that asks you to start Docker and rebuild, deploy to Vercel, or select a provider explicitly in your sandbox file. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting).

## The build records the choice

`eve build` stores the selected provider in the build's prepared sandbox artifact. At runtime, `DefaultSandbox` reads the recorded provider and does not check for Vercel or Docker again, so the build and the server it produces always use the same provider, even when the server runs on a different host. To change the provider, rebuild where the provider you want is available.

Each session also records the provider that created its sandbox. If a later build selects a different provider, a session that resumes on the new build starts a fresh sandbox from the new provider, without the old sandbox's files. eve does not delete the old sandbox: a Vercel Sandbox stays in your Vercel project, and a Docker container stays on the Docker host until you remove it.

## Environment options

`DefaultSandbox.environment()` accepts options for each provider it might select. eve passes only the selected provider's options and ignores the rest:

```ts
import { DefaultSandbox, defineSandbox } from "eve/sandbox";

export const environment = DefaultSandbox.environment({
  prepare: async (sandbox) => {
    await sandbox.writeTextFile({ path: "notes/README.md", content: "Analysis notes\n" });
  },
  docker: { env: { APP_MODE: "agent" } },
  vercel: { region: "iad1" },
  justBash: { autoInstall: false },
});

export default defineSandbox(() => environment.open());
```

| Option     | Used when             | Accepts                                                                                                                             |
| ---------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `prepare`  | Any provider          | Setup captured in the prepared environment. Replaces a `prepare` set inside the provider options.                                   |
| `docker`   | Docker is selected    | The options of [`DockerSandbox.environment()`](/docs/sandbox/docker#environment-options), such as `image`, `env`, and `pullPolicy`. |
| `vercel`   | Vercel is selected    | The options of [`VercelSandbox.environment()`](/docs/sandbox/vercel), such as `region`, `resources`, and credentials.               |
| `justBash` | just-bash is selected | The options of [`JustBashSandbox.environment()`](/docs/sandbox/just-bash), such as `autoInstall` and `customCommands`.              |

Keep a shared `prepare` callback portable, because it runs on whichever provider eve selects. just-bash runs no native binaries, so commands such as `apt-get` fail there during `eve dev`.

On Vercel, when the environment has no `prepare` callback, workspace seed, skill files, or `source`, eve skips the snapshot and creates each session sandbox directly from the configured `image`, or from eve's base image when none is set. See [Vercel Sandbox](/docs/sandbox/vercel#snapshot-preparation).

## Network policy

Pass `networkPolicy` to `open()`, or call `setNetworkPolicy()` on the session from `ctx.getSandbox(environment)`. eve forwards the policy to the selected provider:

```ts
import { DefaultSandbox, defineSandbox } from "eve/sandbox";

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

Vercel Sandbox accepts every network policy, including domain allow-lists and credential transforms. Docker accepts only `"allow-all"` and `"deny-all"` and rejects any other policy with an error. just-bash always allows network access, so it accepts only `"allow-all"` and rejects any other policy with an error. Use [Vercel Sandbox](/docs/sandbox/vercel) directly when you need domain-level policies in every environment.

Use a provider directly when you need its other `open()` options, such as Vercel compute resources or Drive `mounts`.

---

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)