eve: a sandbox provider
eve is Vercel's framework for durable backend agents, in preview. @shotcup/eve is an eve sandbox provider: each eve session gets one Shotcup saved sandbox, with a workspace that persists across the session's turns and a fresh, limited GocciaScript engine for every run, which answers with a diff and the files it wrote.
The package is not published to npm yet, and neither are the shotcup SDK and @shotcup/ai-sdk it builds on. Once they are:
bun add @shotcup/eve @shotcup/ai-sdk shotcup eve zod@shotcup/eve 0.3 works with eve 0.81 and so needs Node.js 24, as eve does.
Set it up
// agent/sandbox.ts
import { ShotcupSandbox } from "@shotcup/eve";
import { defineSandbox } from "eve/sandbox";
export const environment = ShotcupSandbox.environment({
// SHOTCUP_API_KEY is read from the environment when apiKey is not given
deterministic: true,
});
export default defineSandbox(async () => environment.open());A Shotcup sandbox has no shell, so eve's built-in bash tool does not apply. Turn the default tools off (defineAgent({ defaultTools: false }), or an agent/tools/bash.ts that exports disableTool()) and give the agent a tool that runs code:
// agent/tools/run_script.ts
import { defineTool } from "eve/tools";
import { z } from "zod";
export default defineTool({
description:
"Writes a JavaScript module (ES modules, arrow functions, const/let, for...of) to /workspace/<name>.js " +
"and runs it in the sandbox. Print the answer; write larger results under /out.",
inputSchema: z.object({ name: z.string().regex(/^[a-z0-9-]+$/), code: z.string() }),
async execute({ name, code }, ctx) {
const sandbox = await ctx.getSandbox();
const path = `/workspace/${name}.js`;
await sandbox.writeTextFile({ path, content: code });
const { exitCode, stdout, stderr } = await sandbox.run({ command: `shotcup run ${path}` });
return { path, exitCode, stdout, stderr };
},
});The sandbox keeps the module, so a later turn can run it again or extend it.
How the session maps to a sandbox
- prepare turns the agent's workspace resources and skills into a file set at
/workspace/...and/home/.agents/skills/.... Text stays text; binary files such as images and fonts keep their bytes. - start creates one saved sandbox per eve session from that file set, plus any
filesyou pass toopen(), and records its id. - resume reconnects to the recorded sandbox on later turns and after a restart. A deleted sandbox fails the resume instead of being created again.
- The session's end (completed, expired or failed) deletes its sandbox and files.
sandbox.delete()deletes it earlier, and the nextgetSandbox()starts a fresh one;sandbox.stop()releases nothing, because a saved sandbox holds no compute between runs.
ctx.getSandbox() returns eve's session surface: run, spawn, readFile, readBinaryFile, readTextFile, writeFile, writeBinaryFile, writeTextFile, resolvePath and removePath. Relative paths resolve from /workspace. run({ command }) accepts shotcup run <entry> (or just the entry) with the switches --compat, --ast, --vitest and --canvas, and refuses anything else with an error that says so.
ctx.getSandbox(environment), with the environment exported from agent/sandbox.ts, returns the Shotcup session with two more methods: sandboxId() and lastRun(), the whole last run. After a failed run, lastRun().hint says what to write instead of a construct the language profile leaves out.
Code mode with your own tools
For code mode, the environment's tools declares functions the agent's code may call as tools.<name>(...), and toolHandlers answers them live while the run is going. A handler declared as (input, { signal }) => ... gets a signal that aborts when the run ends or eve aborts the command. A declaration with approval: true pauses the run at its first call, and the session's lastRun() then carries interrupt with the pending calls and the run's continuation token. The command result the agent sees has no token; keep lastRun() out of what a tool returns to the model. Durable code mode explains how a paused run is resumed.
eve keeps the agent's session durable. Shotcup keeps the files, and by default gives each run the same result for the same code and files.
Runs that are safe to retry
eve retries a step that failed, so a tool that runs code may run it twice. The Shotcup session's run and spawn take an idempotencyKey: a retry with the same key and the same command gets the run the first attempt started instead of running the code again. Key it by the eve session and the tool call, which stay the same when eve retries the step. callTimeoutMs sets how long one of the run's live tool calls may wait for its answer; ShotcupSandbox.environment({ callTimeoutMs }) sets it for every run.
const sandbox = await ctx.getSandbox(environment);
const { exitCode, stdout, stderr } = await sandbox.run({
command: `shotcup run ${path}`,
idempotencyKey: `${ctx.session.id}:${ctx.callId}`,
callTimeoutMs: 10_000,
});The time
Runs are deterministic by default: Date.now(), Temporal.Now and performance.now() read 0, the time zone is UTC and Math.random is seeded. For the current time, declare a tool that answers it and mark it replay: "safe", since reading the time may be asked again:
export const environment = ShotcupSandbox.environment({
tools: [{ name: "clock.now", replay: "safe" }],
toolHandlers: { "clock.now": () => new Date().toISOString() },
});The agent's code reads await tools.clock.now(). When a paused run resumes, the calls it made before the pause get their recorded answers, so it reads the same times and takes the same path; calls after the resume are answered live. Reading the clock directly with deterministic: false gives other values on resume, and a call that depends on them is refused.
Drives
ShotcupSandbox.environment({ mounts }) and open({ mounts }) mount drives into every run of the session: a record from the mount path to { drive, mode, version }, where mode is ro (the default), rw or snapshot (read-only) and version an id or latest. Reading a mounted path reads the drive, and writing a read-write one makes a new version. Subagents that write the same drive at once make sibling versions, which client.drives.merge reconciles.
export default defineSandbox(() =>
environment.open({
mounts: {
"/data": { drive: "prices", mode: "snapshot" },
"/out": { drive: "results", mode: "rw" },
},
}),
);This page as Markdown: /docs/eve.md