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: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
.env.local. eve dev loads it automatically.
.env.local
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.connectresumes 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.spawnand moves files withsandbox.files.stop()pauses the sandbox. prepare()bakes workspace files and setup into a snapshot. See Bake files and setup into a snapshot.
agent/lib/superserve-sandbox.ts:
agent/lib/superserve-sandbox.ts
idleTimeoutSeconds and autoDeleteSeconds to environment() to change this.
Use it as the agent’s sandbox
Pointagent/sandbox.ts at the provider:
agent/sandbox.ts
Run the agent
Start the dev server:scripts/chat.ts. It uses eve’s client to send two turns to one session, then ends the session:
scripts/chat.ts
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’snetworkPolicy to open(). The provider maps it to Superserve network rules when it creates the sandbox:
agent/sandbox.ts
scripts/ask.ts:
scripts/ask.ts
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 underagent/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
eve dev starts builds the snapshot. Each new session then starts from it, with the file and the tool in place:
.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
bashtool 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 devto pause the sandbox. The idle timeout pauses it. Runeve dev --resumeto continue a session after a restart. -
Commands run as
rootin/workspace. The default sandbox haspython3but nopython. Useprepare, 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.