---
title: "eve: a sandbox provider"
description: "@shotcup/eve gives each eve session a saved sandbox, with a code-running tool, live tools, approvals and drives."
canonical: "https://shotcup.dev/docs/eve"
last_updated: "2026-10-18"
---
# eve: a sandbox provider

[eve](https://eve.dev) 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:

```sh
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

```ts
// 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:

```ts
// 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 `files` you pass to `open()`, 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 next
  `getSandbox()` 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](https://shotcup.dev/docs/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](https://shotcup.dev/docs/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.

```ts
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:

```ts
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](https://shotcup.dev/docs/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.

```ts
export default defineSandbox(() =>
  environment.open({
    mounts: {
      "/data": { drive: "prices", mode: "snapshot" },
      "/out": { drive: "results", mode: "rw" },
    },
  }),
);
```
