Vercel Eve

Vercel Eve agents can use Sandbox0 as their sandbox backend through the @sandbox0/eve adapter for the Sandbox0 JavaScript SDK.

Use this integration when you want Eve's agent runtime and tool model, but want sandbox execution, prewarm snapshots, pause/resume, and network controls to run on Sandbox0.

The adapter implements Eve's SandboxBackend lifecycle:

• Eve prewarm() claims a Sandbox0 sandbox, runs bootstrap, writes seed files, pauses the sandbox, and captures a RootFS snapshot
• Eve create() claims a fresh Sandbox0 sandbox from the prewarmed rootfs snapshot
• Eve durable session metadata stores the Sandbox0 sandboxId, so later turns can resume the same sandbox
• Eve file, command, and network policy calls are translated to Sandbox0 SDK calls

Requirements#

• an Eve 0.11.x application using the SandboxBackend contract shown here
• Node.js 24 or newer for Eve 0.11.x
• sandbox0 and @sandbox0/eve in the app dependencies
• a Sandbox0 API key
• a Sandbox0 template with Bash and /workspace; the hosted default template already satisfies this

Eve template state is captured with Sandbox0 rootfs snapshots, and durable session state is preserved by reusing or resuming the session sandbox.

Install#

bash
npm install [email protected] [email protected] @sandbox0/[email protected]

These are the reviewed versions for this guide. Newer Eve releases have changed the sandbox API and file layout; do not assume the adapter's broad peer-version declaration makes this configuration compatible with every newer release. Configure Eve's model-provider credentials separately from the Sandbox0 key.

@sandbox0/[email protected] fixes the text-file encoding type contract so the configuration below works directly with Eve 0.11.x under strict TypeScript. Version 0.10.4 used a narrower BufferEncoding declaration and is not compatible with this direct configuration.

If you deploy on Vercel or another hosted runtime, add the Sandbox0 credentials to that environment:

bash
SANDBOX0_TOKEN=s0_...
SANDBOX0_BASE_URL=https://api.sandbox0.ai
SANDBOX0_TEMPLATE=default

SANDBOX0_BASE_URL defaults to https://api.sandbox0.ai. It can explicitly override the API endpoint. See Deployment Options for current service availability.

Configure Eve#

Create or update agent/sandbox/sandbox.ts:

typescript
import { defineSandbox } from "eve/sandbox";
import { sandbox0 } from "@sandbox0/eve";

export default defineSandbox({
    backend: sandbox0({
        template: process.env.SANDBOX0_TEMPLATE ?? "default",
        networkPolicy: "allow-all",
    }),
    revalidationKey: () => "sandbox0-eve-v1",
    async bootstrap({ use }) {
        const sandbox = await use();
        const result = await sandbox.run({
            command: "python3 --version",
        });
        if (result.exitCode !== 0) throw new Error(result.stderr);
    },
    async onSession({ use }) {
        await use({ networkPolicy: "allow-all" });
    },
});

Eve will pass files under agent/sandbox/workspace/ to the backend as seed files. The Sandbox0 adapter writes those files under /workspace, matching Eve's workspace contract.

text
agent/sandbox/
    sandbox.ts
    workspace/
        README.md
        scripts/
            check.sh

The example above creates /workspace/README.md and /workspace/scripts/check.sh inside the Sandbox0 sandbox.

How Prewarm Works#

Eve calls prewarm() before serving traffic for a sandbox definition that has bootstrap or seed files.

The Sandbox0 adapter performs this sequence:

1. Claim a Sandbox0 sandbox from the configured template.
2. Run Eve bootstrap inside that sandbox.
3. Write Eve seed files into /workspace.
4. Perform a filesystem-only pause and wait for the paused state.
5. Create a Sandbox0 RootFS snapshot from that paused sandbox.
6. Store the mapping from Eve templateKey to Sandbox0 snapshotId under .eve/sandbox0/.

At runtime, Eve calls create() with the same templateKey. The adapter reads the stored mapping and claims a new Sandbox0 sandbox with snapshotId.

Keep the .eve/sandbox0/ registry available to the runtime as well as the build process; it is a local file mapping, not a hosted Sandbox0 template registry. The referenced snapshots must remain available in the same team and region. Expired or deleted snapshots require a new prewarm. A snapshot contains the whole writable RootFS, including files outside /workspace.

Session Persistence#

Eve durable sessions keep backend metadata between turns. The Sandbox0 adapter stores the live sandboxId in that metadata.

When the same Eve session continues later:

• if the Sandbox0 sandbox is still running, the adapter opens it
• if it is paused, the adapter resumes it first
• if it is missing, Eve can rebuild the template and create a fresh session sandbox

The adapter's resume call uses filesystem-only resume; it does not restore retained process memory. A missing live sandbox is rebuilt from the prewarm snapshot, so changes made during that lost session are not recovered from its metadata alone.

Handle disposal defaults to dispose: "keep": it does not pause or delete live sandbox compute. Set dispose: "delete" for disposable sessions, or manage retention and lifecycle explicitly. Live sandbox TTLs can be supplied through backend config: { ttl, hardTtl }.

This is different from the prewarm sandbox. The prewarm sandbox is only used to build the reusable rootfs snapshot.

Prewarm Sandbox TTL#

The adapter sets a one-hour hard TTL when it claims the prewarm sandbox. Time spent in bootstrap counts toward that deadline; it is not a fresh hour after snapshot creation. The paused sandbox remains inspectable until deletion, while the named snapshot has its own retention and expiry rules.

You can change that behavior:

typescript
import { defineSandbox } from "eve/sandbox";
import { sandbox0 } from "@sandbox0/eve";

export default defineSandbox({
    backend: sandbox0({
        template: "default",
        prewarmSandboxHardTtlSec: 3600,
        deletePrewarmSandbox: false,
    }),
});

Set deletePrewarmSandbox: true if you want the adapter to delete the prewarm sandbox after the rootfs snapshot is captured.

Network Policy#

The adapter maps Eve's basic sandbox network policies to Sandbox0 network policy:

Example:

typescript
export default defineSandbox({
    backend: sandbox0({
        template: "default",
        networkPolicy: {
            allow: ["github.com", "registry.npmjs.org"],
        },
    }),
});

Template rules and platform policy still apply; these mappings do not remove mandatory restrictions. Eve transform and forwardURL rules are rejected. Per-request match fields are not preserved by the adapter: a domain entry is translated into a destination allow rule. Use Sandbox0 protocol controls and credential rules for request-level restrictions and native credential injection.

Run Locally#

Use Eve's normal local commands:

bash
export SANDBOX0_TOKEN=s0_...
export SANDBOX0_BASE_URL=https://api.sandbox0.ai
export SANDBOX0_TEMPLATE=default

npm exec -- eve build
npm exec -- eve start --host 0.0.0.0 --port 3207

Then call the Eve app through Eve's client or your app's channel endpoint.

For local environments behind an HTTP proxy, make sure the Node process can reach both the Sandbox0 API and your model provider, and that localhost requests are excluded from the proxy.

bash
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1

Those variables alone do not configure every Node transport. Configure the Node HTTP client/fetch dispatcher and any WebSocket transport to use the proxy and bypass local addresses; the adapter does not install a global proxy agent.

Production Guidance#

• Use a dedicated Sandbox0 API key for the Eve deployment.
• Set a hard TTL for live session sandboxes if your application does not manage long-lived sessions.
• Keep /workspace available in custom templates; Eve tools and seed files assume that path.
• Use Sandbox0 rootfs snapshots for Eve template state, and use an external system for data that must be shared independently of sandbox identity.
• Delete stale .eve/sandbox0/ registry files when you intentionally remove the corresponding Sandbox0 rootfs snapshots.

Next Steps#