Skip to main content
eve is Vercel’s framework for durable backend agents. Each eve session gets one sandbox, where the agent’s bash, read_file, and write_file tools run. eve’s defineSandboxProvider API lets you plug in your own backend. This page builds a provider that gives every eve session its own Superserve sandbox, so the commands the model runs and the files it writes stay in an isolated VM. The model API key stays in your app; the sandbox never sees it.

Setup

eve needs Node.js 24 or later. Create an agent and add the Superserve SDK:
This page uses eve 1.0.0-rc.14 and @superserve/sdk 0.12.0. The examples call Anthropic directly, so they need no Vercel AI Gateway credentials. Set the model in agent/agent.ts:
agent/agent.ts
Put your keys in .env.local. eve dev loads it automatically.
.env.local
See API keys to create a Superserve API key.

Add the provider

The provider maps eve’s sandbox lifecycle to the Superserve SDK:
  • start() creates a sandbox the first time a session uses one. It tags the sandbox with a hash of the eve session id, so a later call finds the same sandbox.
  • resume() reconnects to that sandbox in later steps and after a server restart. Sandbox.connect resumes it if it is paused. If the platform is moving the sandbox (migrating), the provider waits up to a minute and tries again.
  • onSessionEnd() deletes the sandbox when the eve session ends.
  • The connection runs eve’s commands with sandbox.commands.spawn and moves files with sandbox.files. stop() pauses the sandbox.
  • prepare() bakes workspace files and setup into a snapshot. See Bake files and setup into a snapshot.
Save it as agent/lib/superserve-sandbox.ts:
agent/lib/superserve-sandbox.ts
A sandbox pauses after 15 idle minutes and is deleted after it stays paused for one day. Pass idleTimeoutSeconds and autoDeleteSeconds to environment() to change this.

Use it as the agent’s sandbox

Point agent/sandbox.ts at the provider:
agent/sandbox.ts

Run the agent

Start the dev server:
You can chat in the terminal UI. To drive the agent from code, save this script as scripts/chat.ts. It uses eve’s client to send two turns to one session, then ends the session:
scripts/chat.ts
In a second terminal, run it:
The hostname is sandbox- plus the first 8 characters of the Superserve sandbox id. Both turns ran in the same sandbox, and the second turn read the file the first turn wrote. Ending the session deleted the sandbox.

Restrict network access

Pass eve’s networkPolicy to open(). The provider maps it to Superserve network rules when it creates the sandbox:
agent/sandbox.ts
To send one message from the command line, save this script as scripts/ask.ts:
scripts/ask.ts
With this policy, a request to example.com succeeds and a request to any other host fails:
"deny-all" blocks all outbound traffic, and "allow-all" adds no rules. subnets.allow becomes CIDR allow rules. In eve, subnets.deny wins over allowed domains and subnets, but in Superserve an allow rule wins over a deny rule. So the provider throws on a policy that has both allow entries and subnets.deny. Superserve rules can’t change or forward requests, so the provider also throws on a policy with transform or forwardURL rules.

Bake files and setup into a snapshot

Files under agent/sandbox/workspace/ seed /workspace in every new sandbox. eve’s prepare option runs setup once per template, not once per session. When the agent has either, the provider’s prepare() runs them in a builder sandbox and takes a snapshot. New sandboxes start from that snapshot. eve needs the sandbox file at agent/sandbox/sandbox.ts when the agent/sandbox/ folder exists. Move it there, and add a seed file:
agent/sandbox/sandbox.ts
agent/sandbox/workspace/NOTES.md
The first sandbox access after eve dev starts builds the snapshot. Each new session then starts from it, with the file and the tool in place:
The provider caches the snapshot id in eve’s storage directory (.eve/sandbox-cache/ under eve dev). It reuses the snapshot until the workspace files, the prepare code, or the sandbox file change, or until the snapshot is deleted. eve build runs prepare() too, so each build can take a new snapshot. Delete snapshots you no longer need with Snapshot.deleteById. See Snapshot limits.

Good to know

  • The lookup in start() is not atomic. If two processes create a sandbox for the same session at the same time, each keeps the oldest one and deletes its own, but a narrow race can still leave two sandboxes. The extra one is deleted when the session ends.
  • eve’s bash tool waits up to 60 seconds by default. A longer command keeps running in the sandbox, and the model can check on it in a later call. The provider sets no command timeout for this reason, so the idle timeout is the limit.
  • Don’t rely on stopping eve dev to pause the sandbox. The idle timeout pauses it. Run eve dev --resume to continue a session after a restart.
  • Commands run as root in /workspace. The default sandbox has python3 but no python. Use prepare, or start from a template that has the tools you need:
    agent/sandbox.ts
  • Each Superserve sandbox is a full VM, so one session’s processes and files never reach another session’s.

Resources

eve sandbox docs

Sandbox environments, workspace seeds, and prepare in eve.

Custom sandbox providers

The defineSandboxProvider contract this provider implements.

Sandbox lifecycle

Pause, resume, idle timeout, and auto-delete.

Run commands

Options for commands.spawn, including environment variables and working directory.