eve 0.63.0 → 0.64.1

package/dist/src/shared/sandbox-definition.d.ts

@@ -1,112 +0,0 @@
-import type { SandboxSession } from "#shared/sandbox-session.js";
-import type { SandboxBackend } from "#shared/sandbox-backend.js";
-import type { SessionContext } from "#context/session-context.js";
-/**
- * Opens the template session inside a `bootstrap` hook. Optional `options`
- * (typed by the backend's bootstrap-use options `BO`) are applied to the
- * template before the snapshot is captured. Resolves to the
- * {@link SandboxSession} to operate on.
- */
-export type SandboxBootstrapUseFn<O = Record<string, never>> = (options?: O) => Promise<SandboxSession>;
-/**
- * Opens the live sandbox session inside an `onSession` hook. Optional
- * `options` (typed by the backend's session-use options `SO`) are applied
- * to the live session. Resolves to the {@link SandboxSession} for the
- * current turn.
- */
-export type SandboxSessionUseFn<O = Record<string, never>> = (options?: O) => Promise<SandboxSession>;
-/**
- * Argument passed to a sandbox `bootstrap` hook. `use(options?)` opens the
- * template session that the snapshot is captured from; backend-specific
- * `options` (typed by the backend's bootstrap-use options `BO`) are applied
- * to that template.
- */
-export interface SandboxBootstrapContext<O = Record<string, never>> {
-    readonly use: SandboxBootstrapUseFn<O>;
-}
-/**
- * Argument passed to a sandbox `onSession` hook, invoked once per live
- * session. `ctx` contains the active session metadata; sandbox access during
- * initialization goes through `use(options?)`, which opens the live session
- * and applies backend-specific `options` (typed by the backend's session-use
- * options `SO`).
- */
-export interface SandboxSessionContext<O = Record<string, never>> {
-    readonly ctx: Pick<SessionContext, "session">;
-    readonly use: SandboxSessionUseFn<O>;
-}
-/**
- * Resolves a build-time revalidation key for a bootstrap snapshot. eve
- * evaluates it during compile/build and freezes the result into compiled
- * artifacts. Supply one only for external inputs that affect bootstrap
- * output; authored source and managed seeds are tracked automatically.
- */
-export type SandboxRevalidationKeyFn = () => Promise<string> | string;
-/**
- * Public sandbox definition authored in `agent/sandbox.ts` (shorthand)
- * or `agent/sandbox/sandbox.ts` (folder layout, when paired with an
- * authored `sandbox/workspace/` subtree).
- *
- * Each agent (and each subagent) owns exactly one sandbox. When the
- * module file is absent the framework auto-provides a default sandbox
- * via `defaultSandbox()`. Authors override lifecycle and backend by
- * creating `agent/sandbox.ts` (or `agent/sandbox/sandbox.ts` when they
- * also want a workspace folder); subagents override independently via
- * `subagents/<name>/sandbox.ts` (or the folder form) and do not inherit
- * their parent's sandbox (skill seeds differ per agent).
- */
-interface SandboxDefinitionBase<BO = Record<string, never>, SO = Record<string, never>> {
-    /**
-     * Backend that runs this sandbox.
-     *
-     * Accepts either a {@link SandboxBackend} value or a zero-arg factory
-     * function that returns one. The factory form is invoked lazily on
-     * first framework access and the result is memoized for the lifetime
-     * of the process, so backend-internal state (such as the Vercel
-     * backend's prewarmed-template cache) is preserved across every call.
-     * Use the factory form to defer evaluation, for example when create
-     * options depend on environment variables that aren't set at module
-     * load time:
-     *
-     * ```ts
-     * defineSandbox({
-     *   backend: () => vercel({ env: { TOKEN: process.env.TOKEN ?? "" } }),
-     * });
-     * ```
-     *
-     * When this field is omitted, eve substitutes `defaultSandbox()` at
-     * runtime, which picks the best available backend: `vercel()`
-     * on hosted Vercel (where `process.env.VERCEL` is set), then Docker,
-     * microsandbox, or just-bash
-     * everywhere else. Set `backend` explicitly to pin the sandbox to a
-     * specific backend regardless of environment.
-     */
-    readonly backend: SandboxBackend<BO, SO> | (() => SandboxBackend<BO, SO>);
-    /** Human-readable description of this sandbox, surfaced in tooling. */
-    readonly description?: string;
-    /**
-     * Runs once per live session before authored steps use the sandbox.
-     * Call `input.use(options?)` to open the session and apply per-session
-     * backend options (typed by `SO`).
-     */
-    onSession?(input: SandboxSessionContext<SO>): Promise<void> | void;
-}
-export interface SandboxDefinitionWithBootstrap<BO = Record<string, never>, SO = Record<string, never>> extends SandboxDefinitionBase<BO, SO> {
-    bootstrap(input: SandboxBootstrapContext<BO>): Promise<void> | void;
-    /**
-     * Optional build-time revalidation key for the reusable sandbox
-     * snapshot produced by {@link bootstrap}. eve evaluates this
-     * function during compile/build, stores the resolved string in
-     * compiled artifacts, and uses that frozen value for both prewarm and
-     * runtime session create. Authored sandbox source and
-     * framework-managed seed contents are included automatically; provide
-     * this key only for external inputs that affect bootstrap output.
-     */
-    readonly revalidationKey?: SandboxRevalidationKeyFn;
-}
-export interface SandboxDefinitionWithoutBootstrap<BO = Record<string, never>, SO = Record<string, never>> extends SandboxDefinitionBase<BO, SO> {
-    bootstrap?: undefined;
-    readonly revalidationKey?: never;
-}
-export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = SandboxDefinitionWithBootstrap<BO, SO> | SandboxDefinitionWithoutBootstrap<BO, SO>;
-export {};

package/dist/src/shared/sandbox-definition.js

@@ -1 +0,0 @@
-export{};

package/docs/sandbox.mdx

@@ -1,342 +0,0 @@
----
-title: "Sandbox"
-description: "The agent's isolated bash environment, including built-in file tools, a seeded /workspace, backends, lifecycle, and network policy."
----
-
-The sandbox is the agent's isolated bash environment: a filesystem rooted at `/workspace` where it can run shell commands, execute scripts, and read or write files without ever touching your app runtime. Every eve agent has exactly one. The default `bash`, `read_file`, and `write_file` tools target it; you can also add the framework's `glob` and `grep` tools or access it from authored code.
-
-A working sandbox exists by default, with nothing to author. eve selects a framework-provided `defineSandbox({})` source for each local agent; `agent/sandbox.ts` or `agent/sandbox/sandbox.ts` replaces that source. Override it only to add setup, seed files, pick a backend, or lock down the network.
-
-The default sandbox is not a substitute for configuring network policy, credentials, retention, deletion, or other controls your application requires.
-
-## Using the sandbox
-
-The model already has shell and file access through the default tools:
-
-| Tool                       | Does                                |
-| -------------------------- | ----------------------------------- |
-| `bash`                     | run a shell command in the sandbox  |
-| `read_file` / `write_file` | read/write files under `/workspace` |
-
-These tools run with `/workspace` as the working directory. The model-facing file tools accept both absolute paths and paths beginning with `$HOME/`; eve resolves the latter inside the sandbox before reading, writing, or searching. Any authored runtime function (a tool, a step, a model callback) can get a live sandbox handle with `ctx.getSandbox()`.
-
-```ts title="agent/tools/run_analysis.ts"
-import { defineTool } from "eve/tools";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Run a Python analysis script and return its output.",
-  inputSchema: z.object({ script: z.string() }),
-  async execute({ script }, ctx) {
-    const sandbox = await ctx.getSandbox();
-    await sandbox.writeTextFile({ path: "analysis/run.py", content: script });
-    const result = await sandbox.run({ command: "python analysis/run.py" });
-    if (result.exitCode !== 0) {
-      throw new Error(
-        `Analysis failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
-      );
-    }
-    return { stdout: result.stdout };
-  },
-});
-```
-
-`ctx.getSandbox()` takes no arguments, is async, and only works inside authored runtime execution.
-
-`sandbox.run()` resolves with `{ exitCode, stdout, stderr }` when the process exits, including a nonzero exit. Check `exitCode` before reporting success or using generated files. Throw from a tool to report a failed operation to the model, and throw from `bootstrap` to prevent eve from caching an incomplete setup. The built-in `bash` tool returns all three fields so the model can interpret command results itself.
-
-`/workspace` is one namespace across every backend, so `/workspace/foo` points at the same file whether the backend is local or Vercel. When you need to interpolate a path into a generated command, `sandbox.resolvePath("repo/build.py")` anchors a relative path to its absolute `/workspace/repo/build.py` form.
-
-The handle does more than `run` and `writeTextFile`. In every method, relative paths resolve from `/workspace` and absolute paths pass through untouched:
-
-| Method                                   | Does                                                                                            |
-| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `run({ command })`                       | run one command, block until it exits, return `{ exitCode, stdout, stderr }`                    |
-| `spawn(options)`                         | launch a long-running process (server, watcher) and return a `SandboxProcess` handle            |
-| `readTextFile` / `writeTextFile`         | read/write a UTF-8 (or specified encoding) file; `readTextFile` supports 1-based line ranges    |
-| `readBinaryFile` / `writeBinaryFile`     | read/write raw bytes (images, archives, anything non-text)                                      |
-| `readFile` / `writeFile`                 | stream a file in/out as bytes                                                                   |
-| `removePath({ path, force, recursive })` | delete one file or directory; `force` ignores missing paths, `recursive` removes non-empty dirs |
-| `resolvePath(path)`                      | anchor a relative path to its absolute `/workspace/...` form                                    |
-| `setNetworkPolicy(policy)`               | change egress policy mid-turn (backend-dependent; see [Network policy](#network-policy))        |
-
-Since `run` blocks until the command exits, use `spawn` when the process should keep running while the agent does other work:
-
-```ts
-const sandbox = await ctx.getSandbox();
-const server = await sandbox.spawn({ command: "python -m http.server 8000" });
-// ...do other work against the server...
-await server.kill();
-```
-
-A `SandboxProcess` exposes `stdout`/`stderr` byte streams, `wait()` (resolves with the exit code), and `kill()` (idempotent).
-
-`sandbox.id` is a stable per-session identifier that persists across reconnects to the same logical session. Use it as the cache key for per-session state that must outlive individual step executions.
-
-The option types (`SandboxSpawnOptions`, `SandboxReadBinaryFileOptions`, `SandboxWriteBinaryFileOptions`, and so on) are named exports from `eve/sandbox`, alongside `SandboxProcess`.
-
-## Inbound attachments
-
-Before the first model step, eve writes byte-backed AI SDK `file` parts under
-`/workspace/attachments` and stores a sandbox reference in session history.
-For provider calls, images up to 3 MiB and PDFs up to 20 MiB are restored as
-bytes; other files become text references to their sandbox paths. Unresolved
-remote URLs and legacy AI SDK `image` parts are not staged.
-
-## Seeding `/workspace`
-
-Mount authored files into the sandbox at session start by placing them under `agent/sandbox/workspace/`. This requires the folder layout (`agent/sandbox/sandbox.ts`), not the top-level shorthand:
-
-```text
-agent/sandbox/
-  sandbox.ts                ← optional override (see below)
-  workspace/
-    schema.sql              ← lands at /workspace/schema.sql
-    scripts/run.sh          ← lands at /workspace/scripts/run.sh
-```
-
-Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and eve lists the top-level entries to the model in the prompt automatically. `agent/skills/` files are materialized separately under `$HOME/.agents/skills/`, so `agent/sandbox/workspace/skills/...` is an ordinary workspace subtree when you choose to author one.
-
-## Overriding the sandbox
-
-To add setup, seed files, or pick a backend, author `defineSandbox`. There are two layouts:
-
-- `agent/sandbox.ts`: shorthand. Use it when you need only a definition, no seeded files.
-- `agent/sandbox/sandbox.ts`: folder layout. Use it when you also seed `agent/sandbox/workspace/**`. If both exist, the folder layout wins.
-
-```ts title="agent/sandbox/sandbox.ts"
-import { defineSandbox } from "eve/sandbox";
-import { vercel } from "eve/sandbox/vercel";
-
-export default defineSandbox({
-  backend: vercel({ resources: { vcpus: 2 } }),
-  revalidationKey: () => "repo-bootstrap-v1",
-  async bootstrap({ use }) {
-    const sandbox = await use();
-    const result = await sandbox.run({ command: "sudo apt-get install -y jq" });
-    if (result.exitCode !== 0) {
-      throw new Error(
-        `Sandbox setup failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
-      );
-    }
-  },
-  async onSession({ use }) {
-    await use({ networkPolicy: "deny-all" });
-  },
-});
-```
-
-`defineSandbox` and `defaultBackend` live on `eve/sandbox`. Omit `backend` and the runtime falls back to `defaultBackend()` (see [Backends](#backends)).
-
-### Sharing a parent's sandbox
-
-Sandbox definitions use two distinct forms. Pass an object to give an agent or subagent an independent sandbox. Passing a callback to `defineSandbox` opts a declared subagent into sharing: return `parent.sandbox` to select the dispatching agent's exact live sandbox. A raw function export remains a zero-argument definition factory.
-
-```ts title="agent/subagents/reviewer/sandbox.ts"
-import { defineSandbox } from "eve/sandbox";
-
-export default defineSandbox(({ parent }) => {
-  if (parent === null) throw new Error("reviewer must run as a child");
-  return parent.sandbox;
-});
-```
-
-The parent and child then see the same files, processes, `/workspace`, and sandbox home. Nested children that also select `parent.sandbox` keep using the same owning sandbox rather than creating another one. The owning sandbox's `bootstrap` and `onSession` hooks remain authoritative; the child cannot add its own sandbox hooks or backend configuration.
-
-An inheriting child must not declare managed files under its own `sandbox/workspace/` or `skills/` directories, including dynamic skills. Eve rejects that configuration before execution. Remove the child resources when the shared workspace is sufficient, or give the child its own sandbox when it needs independently seeded files or skills.
-
-The built-in `agent` self-delegation path continues to share the root agent's sandbox automatically.
-
-## Backends
-
-The backend decides where the sandbox runs. eve ships four pinned factories from nested `eve/sandbox/*` imports plus an availability-aware default from `eve/sandbox`:
-
-| Backend            | Runs the sandbox                                                                               |
-| ------------------ | ---------------------------------------------------------------------------------------------- |
-| `vercel()`         | on [Vercel Sandbox](https://vercel.com/docs/sandbox).                                          |
-| `docker()`         | locally in a Docker container, driven through the `docker` CLI.                                |
-| `microsandbox()`   | locally in a lightweight [microsandbox](https://www.npmjs.com/package/microsandbox) VM.        |
-| `justbash()`       | locally in the pure-JS `just-bash` interpreter (no daemon or VM, but no real binaries either). |
-| `defaultBackend()` | picks the best available: Vercel Sandbox on hosted Vercel → Docker → microsandbox → just-bash. |
-
-Configuring a pinned factory uses that backend unconditionally. `docker()` always requires a reachable Docker daemon, and `vercel()` always creates hosted sandboxes (including from local dev, with Vercel credentials).
-
-With `backend` omitted, eve uses `defaultBackend()`, which resolves on first use in priority order:
-
-1. **Vercel Sandbox** when deploying on Vercel (`process.env.VERCEL` is set), since local container/VM runtimes can't run there.
-2. **Docker** when a daemon is reachable through a Docker-compatible `docker` CLI (Docker Desktop, OrbStack, Colima, Podman via its docker-compatible CLI; override the binary with `EVE_DOCKER_PATH`).
-3. **microsandbox** when the host supports it: macOS on Apple Silicon, or glibc Linux with KVM enabled.
-4. **just-bash** as the dependency-free fallback.
-
-By default, Docker and microsandbox pull `ghcr.io/vercel/eve` while Vercel Sandbox pulls `vcr.vercel.com/vercel/eve/base`. Each image tag matches the installed eve version without build metadata: a commit tarball version such as `0.56.0+git.4c27b3e37fa36d84` uses image tag `0.56.0`. Set `EVE_SANDBOX_IMAGE_TAG` to replace the version-derived tag for these default images. An explicit `image` passed to `docker()`, `microsandbox()`, or `vercel()` takes precedence. A snapshot `source` on `vercel()` takes precedence over its `image` because Vercel Sandbox treats them as mutually exclusive.
-
-On every backend, authored commands run as the non-root `vercel-sandbox` user through a non-interactive `bash -lc` login shell. `/workspace` and `$HOME` are writable, `$HOME/.local/bin` is on `PATH` for user-scoped executables, and system paths such as `/usr/local` stay root-owned. Use passwordless `sudo` when setup genuinely needs system-wide changes; `sudo` resets the environment, so pass through variables like `NPM_CONFIG_PREFIX` explicitly if a privileged step depends on them.
-
-`defaultBackend()` also accepts a keyed bag so each inner backend gets its own typed create options:
-
-```ts
-import { defaultBackend, defineSandbox } from "eve/sandbox";
-
-export default defineSandbox({
-  backend: defaultBackend({
-    vercel: { networkPolicy: "deny-all", resources: { vcpus: 4 } },
-    docker: { networkPolicy: "deny-all" },
-    microsandbox: { memoryMiB: 2048 },
-  }),
-});
-```
-
-### Docker
-
-`docker()` drives the Docker CLI directly. By default, it uses the `ghcr.io/vercel/eve` image tag matching the installed eve version without build metadata. eve creates `/workspace` and verifies Bash during framework setup, before authored bootstrap code runs. Configure it through `docker({ image, env, pullPolicy, networkPolicy })`, and install authored runtime tools in sandbox bootstrap or provide them through a custom image. Templates are committed as local Docker images and reused across sessions when the sandbox source, seed files, `revalidationKey`, and Docker backend options still match. Sessions run as long-lived containers whose filesystems persist `/workspace` changes across turns for the same durable session. `eve dev` prunes stale template images in the background.
-
-### microsandbox
-
-`microsandbox()` runs each sandbox in a lightweight local VM with snapshot-backed templates, a `vercel-sandbox` user, and a firewall capable of domain-level network policies and credential brokering. It is the closest local match to hosted Vercel Sandbox. By default, it uses the `ghcr.io/vercel/eve` image tag matching the installed eve version without build metadata. During framework setup, before authored bootstrap code runs, eve verifies Bash and creates `/workspace` and the sandbox user. Install authored runtime tools in sandbox bootstrap or provide them through a custom image. Supported hosts are macOS on Apple Silicon, or Linux (glibc) with KVM. The `microsandbox` npm package and its VM runtime are not bundled with eve, so `eve dev` installs both automatically when missing (disable with `setup: { autoInstall: false }`); production processes fail with actionable install errors instead.
-
-### just-bash
-
-`justbash()` needs no daemon or VM, but commands run in a simulated bash with a virtual filesystem under `.eve/sandbox-cache/`, with no real binaries (`git`, `node`, package managers) and no network isolation. The `just-bash` package is an optional peer dependency, so `eve dev` installs it into your application automatically when missing (disable with `autoInstall: false`); production processes fail with an actionable install error instead.
-
-Pass `customCommands` to expose a `just-bash` `CustomCommand` inside each live sandbox session. The command participates in shell pipelines, redirections, and exit-code handling like a built-in command:
-
-```ts title="agent/sandbox.ts"
-import { defineSandbox } from "eve/sandbox";
-import { justbash } from "eve/sandbox/just-bash";
-import { decodeBytesToUtf8, defineCommand } from "just-bash";
-
-const uppercase = defineCommand("uppercase", async (_args, context) => ({
-  stdout: decodeBytesToUtf8(context.stdin).toUpperCase(),
-  stderr: "",
-  exitCode: 0,
-}));
-
-export default defineSandbox({
-  backend: justbash({ customCommands: [uppercase] }),
-});
-```
-
-Custom commands are registered on live and reopened sessions, not during template prewarming. They run trusted host application code and create an explicit bridge from the sandbox to that code. Adapters can use this extension point to expose application APIs such as a Capable App's CLI; the outer eve `bash` tool does not automatically provide per-command Capable approvals.
-
-You can also write your own backend. A `SandboxBackend` is an adapter object with a `name`, a `create`, and an optional `prewarm`. It can point at your own container runner, VM pool, internal sandbox service, or another isolation layer, as long as it returns the `SandboxSession` operations eve needs. Handles returned by `create` implement `delete()`, `stop()`, and `shutdown()`. See the `SandboxBackend*` types on `eve/sandbox`.
-
-## Lifecycle
-
-There are two hooks, scoped differently:
-
-- **`bootstrap({ use })`** is template-scoped and runs once when the template is built. Put reusable setup here that every later session inherits, such as cloning a baseline repo, installing dependencies, or seeding files. Call `use()` to get a `SandboxSession`. Only template filesystem state and supported backend metadata carry into later sessions; config like network policy does not. If external inputs affect what bootstrap produces, set `revalidationKey: () => string` so eve knows when to rebuild the template (authored sandbox source and seed contents are already tracked for you).
-- **`onSession({ use, ctx })`** is durable-session-scoped and runs once per session (and again if a sandbox definition change replaces the session's sandbox). Put per-session setup here, including network policy, resources, timeout, per-user credentials, and one-time markers. `ctx` contains only the active session metadata, so it can identify the current principal without exposing runtime lifecycle operations while the sandbox is initializing. Call `use(opts?)` to get a `SandboxSession`; `opts` flow to the backend's update path after create.
-
-If you require a network policy or other configuration for every session, configure it on the backend factory or in `onSession`; do not rely on bootstrap-only configuration.
-
-```ts
-import { defineSandbox } from "eve/sandbox";
-import { vercel } from "eve/sandbox/vercel";
-
-export default defineSandbox({
-  backend: vercel(),
-  async onSession({ use, ctx }) {
-    const sandbox = await use({ networkPolicy: "deny-all" });
-    const user = ctx.session.auth.current;
-    if (user === null) return;
-    await sandbox.writeTextFile({ path: "SESSION_USER.txt", content: `${user.principalId}\n` });
-  },
-});
-```
-
-Sessions are persistent, and how the underlying runtime idles out depends on the backend. On the Vercel backend, the VM times out after a period of inactivity (default 30 minutes); eve preserves the filesystem and resumes the sandbox on the next message while the persisted sandbox remains available. The Docker backend keeps a long-lived container per durable session and persists `/workspace` across turns without that timeout, and the just-bash backend stores its virtual filesystem under `.eve/sandbox-cache/`.
-
-Authored runtime callbacks can stop compute sooner through the handle returned
-by `ctx.getSandbox()`:
-
-```ts
-const sandbox = await ctx.getSandbox();
-await sandbox.stop();
-```
-
-Every built-in backend uses its native lifecycle operation without deleting the
-durable session. Treat the stop as the end of sandbox work in the current
-callback. On the next callback, `ctx.getSandbox()` reopens the same Docker
-container, microsandbox VM or snapshot, or just-bash filesystem and environment.
-Vercel can also automatically resume the same handle on its next I/O operation,
-just as it would after an inactivity timeout. No separate reconnect step or
-stop-specific state is needed. Lifecycle `use()` calls return the I/O-only
-`SandboxSession` because bootstrap and session initialization do not own runtime
-teardown.
-
-### Delete a sandbox
-
-Permanently delete the current session sandbox from an authored runtime callback:
-
-```ts
-const sandbox = await ctx.getSandbox();
-await sandbox.delete();
-```
-
-eve stops compute first, deletes the physical sandbox and its disposable backend state, and clears the saved reconnect state. It preserves reusable template state that contains `bootstrap` and seeded workspace files.
-
-The durable eve session remains active. The next call to `ctx.getSandbox()` provisions a fresh workspace from the current sandbox definition and runs `onSession` again. Files and other workspace changes from the deleted sandbox are not restored.
-
-Backend behavior differs:
-
-- **Vercel Sandbox**: stops the persistent sandbox, deletes its record, and asks Vercel to delete snapshots that no other sandbox uses. Snapshot cleanup runs asynchronously.
-- **microsandbox**: stops and removes the session VM and its persisted state snapshot
-- **Docker and just-bash**: stop compute and discard their session runtime state
-
-Only the session that owns a shared sandbox can delete it. Deleting the owner's sandbox affects every parent or child currently using it. If the backend rejects deletion, eve preserves the current reconnect state so you can retry.
-
-Custom backend handles implement the same boundary in `delete()`: remove the session runtime and disposable persisted state without deleting reusable templates.
-
-Session sandboxes are keyed per durable session, not per deployment, so redeploying your app does not by itself discard them. A definition change to the authored sandbox source, workspace seed content, or `revalidationKey` replaces the sandbox on the next turn and runs `onSession` again.
-
-For sandboxes with `bootstrap`, unrelated agent changes preserve the template and session sandbox keys even when there are no skill or workspace seed files. You do not need to add a seed file or `revalidationKey` solely to preserve reuse across those changes.
-
-Reattachment still depends on the backend retaining its physical sandbox state. If a persisted Vercel sandbox is missing or its saved filesystem snapshot is no longer available, eve deletes the unusable record and creates a replacement from the current template when one is configured. Files and other changes made after the original sandbox was created are not restored automatically. Because the durable session still has the same sandbox key, `onSession` does not run again for this replacement. Persist important artifacts outside the sandbox, and do not rely on `onSession` as the only place that applies security-critical configuration.
-
-When the eve server stops, no sandbox compute outlives it. `eve dev` stops the sandboxes it started when the dev server closes, and a self-hosted production server stops every open sandbox on shutdown (`SIGTERM`/`SIGINT`). Session state persists across the stop — the next server start reattaches each durable session from its stopped container, VM, or snapshot. Custom `SandboxBackend` adapters implement `stop()` for authored runtime calls and `shutdown()` for server teardown. Both stop the underlying compute while keeping the session reattachable from persisted state where the backend supports it; authored `stop()` failures reject, while process-wide shutdown collects and logs failures without blocking teardown.
-
-## Network policy
-
-Egress rules go on the backend factory or in `onSession`'s `use()`. There are three forms:
-
-```ts
-networkPolicy: "allow-all"; // default
-networkPolicy: "deny-all";  // block all egress, including DNS
-
-networkPolicy: {
-  allow: ["ai-gateway.vercel.sh", "*.github.com"],
-  subnets: { deny: ["10.0.0.0/8"] },
-};
-```
-
-Default egress is `allow-all`. For non-public, sensitive, regulated, or production workloads, configure `deny-all` or an explicit allow-list before running untrusted tools or handling sensitive data.
-
-Set it on the factory (`vercel({ networkPolicy: "deny-all" })`) and it applies before authored `bootstrap` code runs; framework-owned base setup may briefly keep egress open to install required packages. Set it in `onSession`'s `use()` to override per-session. A provider-loss replacement with the same sandbox key does not rerun `onSession`, so enforce the security-critical baseline on the factory. If `bootstrap` needs network access, give the factory only the destinations it needs, then narrow the policy further in `onSession`. To change the policy mid-turn, call `sandbox.setNetworkPolicy(...)` on the live handle.
-
-Domain-level allow-lists and credential brokering are supported by `vercel()` and `microsandbox()`. The Docker backend honors only `"allow-all"` and `"deny-all"` (at creation and via `setNetworkPolicy`); the just-bash backend rejects `setNetworkPolicy` entirely.
-
-## Credential brokering
-
-Secrets never enter the sandbox. Instead, the network policy's per-domain `transform` injects credentials at the firewall, so a header can authenticate egress to a host while the secret stays out of the sandbox process entirely:
-
-```ts
-async onSession({ use }) {
-  await use({
-    networkPolicy: {
-      allow: {
-        "github.com": [{ transform: [{ headers: { authorization: "Basic your_base64_credentials_here" } }] }],
-        "*": [],
-      },
-    },
-  });
-}
-```
-
-The `"*": []` catch-all keeps general egress open while the `transform` applies only to `github.com`. For mid-turn brokering, call `setNetworkPolicy` with the same shape. The [Vercel Sandbox docs](https://vercel.com/docs/sandbox) cover the brokering mechanism itself.
-
-## What to read next
-
-- [Subagents](./subagents): each subagent gets its own sandbox, independent of its parent.
-- [Tools](./tools): authored tools run in the app runtime (full `process.env`); only sandbox tools run in the sandbox.
-- [Security model](./concepts/security-model): the app-runtime/sandbox trust boundary in full.
-- [Vercel Sandbox](https://vercel.com/docs/sandbox): platform docs, including credential brokering and persistence limits.