---
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()` lets eve pick the sandbox provider for you. eve picks once, when it prepares the sandbox, and every session the build serves uses that provider. It's also what eve uses when the agent has no sandbox file.

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

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

## How eve selects the provider

eve prepares the sandbox during `eve build`, or during `eve dev` the first time a session opens the sandbox. It takes the first row that matches:

| Where eve prepares the sandbox                                               | Selected provider                             |
| ---------------------------------------------------------------------------- | --------------------------------------------- |
| The `VERCEL` environment variable is set (`vercel build` or a Vercel deploy) | [Vercel Sandbox](/docs/sandbox/vercel)        |
| `docker version` reports a running Linux Docker daemon within five seconds   | [Docker](/docs/sandbox/docker)                |
| `eve dev` or `eve eval`                                                      | [just-bash](/docs/sandbox/just-bash)          |
| A production `eve build`                                                     | 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. Without a provider, `eve build` succeeds and logs that no provider is available. The first session that opens the sandbox then fails. The error asks you to start Docker and rebuild, deploy to Vercel, or select a provider in your sandbox file. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting#defaultsandbox-has-no-sandbox-provider-for-this-build).

## The build records the choice

`eve build` records the selected provider. The server always uses that provider, even on a different host, and doesn't check for Vercel or Docker again. To change the provider, rebuild where the provider you want is available.

When a session continues on a build with a different provider, it starts a fresh sandbox without the old sandbox's files. eve doesn't 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. It passes on only the selected provider's options:

```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 | `autoInstall` and `prepare`. Use [`JustBashSandbox.environment()`](/docs/sandbox/just-bash#experimental-options) for experimental `customCommands` or `filesystem`. |

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

On Vercel, eve skips the snapshot when the environment has no `prepare` callback, workspace seed, skill files, or `source`. Each session sandbox then starts 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

To set a network policy on the selected provider, pass `networkPolicy` to `open()`. You can also call `setNetworkPolicy()` on the sandbox from `ctx.getSandbox(environment)`.

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

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

| Provider  | Accepted policies                                                    |
| --------- | -------------------------------------------------------------------- |
| Vercel    | Every policy, including domain allow-lists and credential transforms |
| Docker    | `"allow-all"` and `"deny-all"`                                       |
| just-bash | `"allow-all"` only, because it always allows network access          |

Other policies throw an error.

Use a provider directly when you need domain-level policies in every environment, or its other `open()` options, such as Vercel compute resources or Drive `mounts`. See [Vercel Sandbox](/docs/sandbox/vercel) and [Docker Sandbox](/docs/sandbox/docker).

---

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)