eve 0.63.0 → 0.64.1

package/docs/meta.json

@@ -2,40 +2,37 @@
   "pages": [
     "---Introduction---",
     "getting-started",
+    "tutorial",
     "concepts",
     "---Build---",
     "agent-config",
     "instructions",
+    "skills",
+    "sandbox",
+    "schedules",
+    "guides/hooks",
     "memory",
     "tools",
     "connections",
     "channels",
-    "skills",
-    "sandbox",
     "subagents",
-    "evals",
-    "guides/session-context",
-    "schedules",
-    "guides/hooks",
-    "guides/dynamic-capabilities",
+    "dynamic-configuration",
     "---Integrate---",
     "install-integrations",
     "extensions",
-    "guides/evaluate",
-    "guides/remote-agents",
-    "protocols",
-    "guides/frontend",
+    "protocols/acp",
     "guides/client",
+    "guides/frontend",
     "---Operate---",
-    "guides/deployment",
     "guides/auth-and-route-protection",
+    "guides/deployment",
+    "evals",
     "guides/instrumentation",
-    "guides/dev-tui",
     "---Reference---",
-    "tutorial",
-    "patterns",
+    "guides/dev-tui",
     "...reference",
     "responsible-use",
-    "[Benchmarks](/benchmarks)"
+    "[Benchmarks](/benchmarks)",
+    "patterns"
   ]
 }

package/docs/patterns/meta.json

@@ -2,10 +2,10 @@
   "title": "Patterns",
   "defaultOpen": false,
   "pages": [
-    "multi-tenant-memory",
     "dynamic-scheduling",
     "durable-cross-channel-notifications",
     "multi-tenant-auth",
-    "multi-tenant-approvals"
+    "multi-tenant-approvals",
+    "../protocols/ucp"
   ]
 }

package/docs/protocols/acp.md

@@ -1,5 +1,5 @@
 ---
-title: "Agent Client Protocol (ACP)"
+title: "Editor Integration (ACP)"
 description: "Use local or deployed eve agents from Agent Client Protocol clients."
 ---
 

package/docs/protocols/ucp.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Universal Commerce Protocol (UCP)"
+title: "Serve a UCP Profile"
 description: "Serve a UCP profile at /.well-known/ucp from a custom eve channel."
 ---
 

package/docs/reference/cli.md

@@ -42,7 +42,7 @@ eve collects CLI telemetry by default to improve the command-line interface. Run
 ## `eve init`
 
 ```bash
-eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
+eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs] [--non-interactive]
 ```
 
 Creates a new agent app or adds an agent to an existing app. Always installs dependencies. New directories also initialize Git.
@@ -57,13 +57,14 @@ Creates a new agent app or adds an agent to an existing app. Always installs dep
 
 Existing packages do not need a target-selection prompt: run `eve init` from the project directory or `eve init path/to/app`. New projects in non-interactive environments need a new directory name, such as `eve init my-agent`.
 
-After scaffolding in an interactive human terminal, eve opens the TUI directly. Noninteractive and coding-agent invocations return without starting an interactive session. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
+After scaffolding in an interactive human terminal, eve opens the TUI directly. Pass `-n` or `--non-interactive` to return after scaffolding instead. It still installs dependencies and follows the normal Git setup behavior. Noninteractive and coding-agent invocations return without starting an interactive session. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
 
-| Flag                   | Type   | Default                    | Description                                                                                                              |
-| ---------------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `--model <model>`      | string | `openai/gpt-5.6-luna-fast` | Set the root agent's AI Gateway model ID.                                                                                |
-| `--reasoning <effort>` | enum   | provider default           | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
-| `--channel-web-nextjs` | flag   | off                        | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
+| Flag                    | Type   | Default                    | Description                                                                                                              |
+| ----------------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--model <model>`       | string | `openai/gpt-5.6-luna-fast` | Set the root agent's AI Gateway model ID.                                                                                |
+| `--reasoning <effort>`  | enum   | provider default           | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
+| `--channel-web-nextjs`  | flag   | off                        | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
+| `-n, --non-interactive` | flag   | off                        | Scaffold and install dependencies without starting development.                                                          |
 
 ## `eve extension`
 
@@ -160,7 +161,7 @@ Run this first when something behaves unexpectedly. It confirms a file was disco
 eve build [--profile <path>] [--skip-sandbox-prewarm]
 ```
 
-Compiles and bundles in an invocation-owned directory under `.eve/builds/`, then publishes the completed host output and prints its path. Scratch workspaces are removed after success or failure.
+Compiles and bundles in an invocation-owned directory under `.eve/builds/`, prepares sandbox artifacts, then publishes the completed host output and prints its path. Scratch workspaces are removed after success or failure. Pass `--skip-sandbox-prewarm` when you only need compiled output, such as before a separate typecheck. Skipping preparation can produce output that cannot start its configured sandbox, so do not deploy that output.
 
 Authored bundles preserve custom Node.js resolution conditions supplied through `--conditions`,
 `-C`, or `NODE_OPTIONS`. For example, `NODE_OPTIONS="--conditions=react-server" eve build`
@@ -169,7 +170,7 @@ keeps a channel's `server-only` imports on the same export used during compilati
 | Flag                     | Type   | Default | Description                                                                                   |
 | ------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------- |
 | `--profile <path>`       | string | off     | Best-effort versioned JSON report with build-phase timings and final output-size measurements |
-| `--skip-sandbox-prewarm` | flag   | off     | Skip sandbox template prewarm for a Vercel build; the output might not be deployable          |
+| `--skip-sandbox-prewarm` | flag   | off     | Skip sandbox preparation; the output might not be deployable                                  |
 
 Use a profile file to establish a repeatable baseline before changing the build pipeline:
 

package/docs/reference/meta.json

@@ -1 +1,4 @@
-{ "title": "Reference", "pages": ["agent-files", "typescript-api", "cli", "telemetry"] }
+{
+  "title": "Reference",
+  "pages": ["cli", "typescript-api", "../guides/session-context", "agent-files", "telemetry"]
+}

package/docs/reference/typescript-api.md

@@ -136,9 +136,9 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 | `eve/memory/file`                                                           | `fileMemory`, `inMemory`, and the conditional document backend contract                                                        |
 | `eve/memory/file/vercel`                                                    | `vercelBlob` and Vercel Blob backend options                                                                                   |
 | `eve/context`                                                               | `defineState`, session and state types                                                                                         |
-| `eve/sandbox`                                                               | `defineSandbox`, backends                                                                                                      |
+| `eve/sandbox`                                                               | `defineSandbox`, provider environments, and sandbox session types                                                              |
 | `eve/instrumentation`                                                       | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types                                       |
-| `eve/instrumentation/otel`                                                  | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                              |
+| `eve/instrumentation/otel`                                                  | `otel`, `otelIntegration`, `localTraces`, OpenTelemetry policy types                                                           |
 | `eve/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
 | [`eve/models`](../guides/evaluate)                                          | Automatic model selection with `auto`                                                                                          |
 | `eve/models/openai`                                                         | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |
@@ -154,29 +154,6 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 
 Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
 
-## Local development capability
-
-Use `getLocalDevCapability()` when an authored tool needs to modify the local application's source tree during an interactive development turn:
-
-```ts
-import { getLocalDevCapability } from "eve/local-dev";
-
-const localDev = getLocalDevCapability();
-if (localDev === undefined) {
-  throw new Error("This tool is available only from a local eve dev client.");
-}
-
-await localDev.withSuspendedSource(async () => {
-  // Write under localDev.appRoot here.
-});
-```
-
-The function returns `LocalDevCapability | undefined`. It returns a capability only while authored code handles a request from a client on the same machine as the `eve dev` server. Deployed runtimes and clients attached over the network receive `undefined`, even when the target is another development server. A local TUI that attaches to an existing headless server receives the capability because availability follows each request rather than the process that started the server.
-
-`appRoot` is the authored application directory containing `package.json` and `agent/`, not the temporary runtime snapshot. `interactiveClient` is `true` when the requesting local client is the dev TUI; check it before starting a flow that requires terminal interaction.
-
-Run source mutations inside `withSuspendedSource()`. It acquires a unique watcher lease, waits for your asynchronous callback to settle, and then releases the lease. Concurrent or nested calls cannot resume each other early, and releasing the final lease rebuilds the runtime artifacts. The callback's return value is returned, and its error is rethrown after release. If suspension cannot be acquired, the callback does not run. If the host cannot confirm release after a retry, the method throws an actionable error; restart `eve dev` before making more source changes.
-
 ## Direct provider models
 
 `openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return eve-owned model instances using the vendored providers. They accept only an optional model ID. Defaults are `gpt-5.6-luna-fast` and `claude-sonnet-5`, respectively.

package/docs/sandbox/default.mdx

@@ -0,0 +1,17 @@
+---
+title: "Default Sandbox"
+description: "Let eve select the sandbox provider for the current environment."
+---
+
+`DefaultSandbox.environment()` preserves eve's standard behavior without exposing provider-specific live creation options.
+
+```ts
+import { DefaultSandbox, defineSandbox } from "eve/sandbox";
+
+export const environment = DefaultSandbox.environment();
+export default defineSandbox(() => environment.open());
+```
+
+On Vercel, it selects [Vercel Sandbox](/docs/sandbox/vercel). Elsewhere, it tries [Docker](/docs/sandbox/docker), [microsandbox](/docs/sandbox/microsandbox), and [just-bash](/docs/sandbox/just-bash), in that order, according to host support.
+
+Use a provider directly when you need its image, VM, network, compute, or mount options.

package/docs/sandbox/docker.mdx

@@ -0,0 +1,29 @@
+---
+title: "Docker Sandbox"
+description: "Create local persistent containers from an image or Dockerfile."
+---
+
+Docker environments can use eve's default image, an existing OCI image, or `agent/sandbox/Dockerfile`.
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { DockerSandbox } from "eve/sandbox/docker";
+
+export const environment = DockerSandbox.image("ghcr.io/acme/agent@sha256:...");
+
+export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
+```
+
+Use `DockerSandbox.environment()` for the default image or `DockerSandbox.dockerfile()` for the colocated Dockerfile convention.
+
+## Environment options
+
+Image, pull policy, environment variables, and `prepare` belong to the reusable environment. During preparation, eve starts a temporary container, hydrates managed resources, runs authored preparation, and commits the result as the recorded template image.
+
+## Live container options
+
+Pass `networkPolicy` to `open()`. Docker supports only `"allow-all"` and `"deny-all"`. The policy applies to the live container, not the prepared image.
+
+A session-owned container keeps writable `/workspace` state in its container filesystem. A stopped container restarts with that state.
+
+See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.

package/docs/sandbox/index.mdx

@@ -0,0 +1,218 @@
+---
+title: "Sandbox"
+description: "Configure the isolated filesystem and command environment used by an eve agent."
+---
+
+Every eve agent has one sandbox rooted at `/workspace`. The built-in `bash`, `read_file`, and `write_file` tools use it. Without an authored sandbox file, eve selects the best available environment automatically.
+
+## Use the sandbox
+
+Authored tools and callbacks access the live sandbox 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 script.",
+  inputSchema: z.object({ script: z.string() }),
+  async execute({ script }, ctx) {
+    const sandbox = await ctx.getSandbox();
+    await sandbox.writeTextFile({ path: "analysis.py", content: script });
+    const result = await sandbox.run({ command: "python analysis.py" });
+    if (result.exitCode !== 0) throw new Error(result.stderr);
+    return result.stdout;
+  },
+});
+```
+
+Relative paths resolve under `/workspace`. `run()` returns `{ exitCode, stdout, stderr }`; a nonzero exit code does not throw automatically. Use `spawn()` for a long-running process.
+
+## Define an environment
+
+A sandbox module exports an environment and returns a sandbox from `defineSandbox()`:
+
+```ts title="agent/sandbox.ts"
+import { DefaultSandbox, defineSandbox } from "eve/sandbox";
+
+export const environment = DefaultSandbox.environment();
+export default defineSandbox(() => environment.open());
+```
+
+`environment.open()` starts the persistent sandbox owned by the current eve session. The `defineSandbox()` selector runs until initialization succeeds, then eve checkpoints the selected provider and its state. Later workflow steps and process restarts call the provider's `resume()` directly without rerunning the selector or `environment.open()`.
+
+Pass options for the live sandbox to `open()`, then configure the returned sandbox before returning it. This initialization runs once for a successfully started durable sandbox:
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { VercelSandbox } from "eve/sandbox/vercel";
+
+export const environment = VercelSandbox.environment();
+
+export default defineSandbox(async ({ session }) => {
+  const sandbox = await environment.open({ networkPolicy: "deny-all" });
+  await sandbox.writeTextFile({ path: ".eve/session", content: session.id });
+  return sandbox;
+});
+```
+
+The environment export is required because `eve build` prepares immutable environment inputs before a session exists.
+
+### Prepare a reusable environment
+
+Use the environment's `prepare` option for setup every new sandbox inherits:
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { VercelSandbox } from "eve/sandbox/vercel";
+
+export const environment = VercelSandbox.environment({
+  prepare: async (sandbox) => {
+    const result = await sandbox.run({
+      command: "sudo apt-get update && sudo apt-get install -y jq",
+    });
+    if (result.exitCode !== 0) throw new Error(result.stderr);
+  },
+});
+
+export default defineSandbox(() => environment.open());
+```
+
+eve runs `prepare` while creating a reusable provider artifact, not once for each live session sandbox. Vercel captures a snapshot; Docker captures an image; microsandbox captures a VM snapshot; and just-bash captures a filesystem template.
+
+During `eve dev`, startup and authored-source rebuilds do not prepare sandbox environments. The first sandbox access prepares all environments in that compiled generation before opening the requested sandbox. This includes environments declared by subagents and extensions, even if they use different providers. Concurrent requests share the preparation work; a failed preparation can be retried on a later access. Optional provider installation and setup can make that first access slow.
+
+`eve build` still prepares environments eagerly. In production, eve passes the recorded artifact directly to the provider when it creates a live sandbox. Production runtime does not rebuild or repair a missing artifact. A missing image, snapshot, or template fails with rebuild or redeploy guidance.
+
+### Reuse native resources across sessions
+
+Built-in environments do not expose cross-session sharing. To reuse native compute or storage across eve sessions, define a custom provider that returns a session-owned logical sandbox view and keeps shared resources outside that view's `stop`, `shutdown`, and `delete` operations. A session-specific path is not an isolation boundary; mutually untrusted sessions require separate native compute or stronger provider-owned isolation.
+
+### Share a parent sandbox
+
+A declared subagent can use its dispatching parent's sandbox explicitly:
+
+```ts title="agent/subagents/reviewer/sandbox.ts"
+import { defineParentSandbox } from "eve/sandbox";
+
+export default defineParentSandbox();
+```
+
+An inheriting subagent cannot declare its own managed workspace or skill files.
+
+## Managed workspace and skills
+
+Use the sandbox directory for authored workspace seeds:
+
+```text
+agent/sandbox/
+  sandbox.ts
+  workspace/
+    schema.sql
+```
+
+Files under `agent/sandbox/workspace/` seed writable `/workspace`. eve copies the seed when it prepares a new environment generation. Existing live sandbox state is not overwritten by later seed changes.
+
+Agent skills are compiled into a separate resource tree and exposed at `$HOME/.agents/skills`. These are stable paths across every built-in provider, so instructions and tools can refer to `/workspace` and `$HOME/.agents/skills`. Do not refer to a concrete home directory or `/eve/resources`, which is provider-internal staging.
+
+Providers receive both trees with explicit metadata:
+
+```ts
+interface SandboxProviderResources {
+  source:
+    | { kind: "none" }
+    | { kind: "inline"; key: string }
+    | { kind: "materialized"; key: string; path: string }
+    | { kind: "reference"; key: string };
+  workspace?: SandboxProviderResourceTree;
+  skills?: SandboxProviderResourceTree;
+}
+
+interface SandboxProviderResourceTree {
+  key: string;
+  files: ResourceFile[];
+  mountPath: string;
+  targetPath: string;
+}
+```
+
+Docker and microsandbox mount the compiled trees read-only under `/eve/resources`, copy workspace seeds into writable `/workspace`, and expose skills read-only where possible. Vercel's snapshot environment writes workspace and skill contents before capturing its snapshot. Custom providers decide whether to upload, mount, or write each tree, but must expose the final target paths before authored preparation runs.
+
+## Custom providers
+
+Define a provider with `defineSandboxProvider()` from `eve/sandbox/provider`. The five generic parameters describe environment options, live options, the prepared artifact, minimal serialized session state, and the provider-specific sandbox session type:
+
+```ts
+import type { SandboxSession } from "eve/sandbox";
+import { defineSandboxProvider } from "eve/sandbox/provider";
+
+export const AcmeSandbox = defineSandboxProvider<
+  { image: string; prepare?: (sandbox: SandboxSession) => Promise<void> },
+  { networkPolicy?: "allow-all" | "deny-all" },
+  { templateId: string },
+  { remoteId: string; version: 1 },
+  SandboxSession
+>({
+  name: "acme",
+  environment(options) {
+    const client = createAcmeClient(options);
+
+    return {
+      async prepare(ctx) {
+        const temporary = await client.createTemporary({
+          files: await ctx.files.list(),
+          resources: ctx.resources,
+        });
+        const sandbox = adaptAcmeSandbox(temporary);
+        await options?.prepare?.(sandbox);
+        return { templateId: (await temporary.capture()).id };
+      },
+
+      async start(ctx, liveOptions, artifact) {
+        const remote = await client.open({
+          identity: sessionIdentity(ctx.session.id, artifact, liveOptions),
+          networkPolicy: liveOptions?.networkPolicy,
+          templateId: artifact.templateId,
+        });
+        return {
+          handle: createHandle(remote),
+          state: { remoteId: remote.id, version: 1 },
+        };
+      },
+
+      async resume(_ctx, artifact, state) {
+        const remote = await client.resume({ id: state.remoteId, templateId: artifact.templateId });
+        return createHandle(remote);
+      },
+    };
+  },
+});
+```
+
+`prepare()` returns the complete JSON-serializable artifact. Core calls `start()` once for a new durable sandbox session and persists its minimal JSON-compatible state. Process restarts call `resume()` with only the current context, that state, and the target deployment's exact artifact. Provider handles implement `onSessionStop()`, `onRuntimeShutdown()`, and `onSessionDelete()`.
+
+Open options belong to `start()` and are not serialized or passed to `resume()`. A provider must put any immutable option-derived data needed for reconnection in its session state. With the current immutable-state contract, `resume()` reconnects existing native state and fails if it is gone rather than recreating callback side effects. A custom provider may define start-only callback fields, but built-in providers initialize the sandbox in `defineSandbox()` after `open()`.
+
+Preparation discovers authored files through `ctx.files`; core keeps project layout and artifact storage keys private. Keep provider SDK values behind the provider. `environment.open()` preserves the provider's sandbox capability type, while the heterogeneous runtime registry erases it to eve's common session surface.
+
+## Providers
+
+| Provider                                   | Use it for                                                                              |
+| ------------------------------------------ | --------------------------------------------------------------------------------------- |
+| [Default](/docs/sandbox/default)           | Automatic provider selection with eve's standard behavior.                              |
+| [Vercel](/docs/sandbox/vercel)             | Snapshot-backed persistent Vercel Sandboxes, domain network policies, and Drive mounts. |
+| [Docker](/docs/sandbox/docker)             | Local containers from the default image, an existing OCI image, or a Dockerfile.        |
+| [microsandbox](/docs/sandbox/microsandbox) | Local lightweight VMs from an OCI image or Dockerfile.                                  |
+| [just-bash](/docs/sandbox/just-bash)       | A pure-JavaScript shell and virtual filesystem without native process isolation.        |
+
+## Lifecycle
+
+Session-owned sandboxes persist across turns and deployments while their provider state remains available. `sandbox.stop()` stops compute without deleting persisted state; a later access resumes that state directly. `sandbox.delete()` clears provider state, so the next `ctx.getSandbox()` reruns the selector and starts a fresh sandbox from the current environment.
+
+Changing sandbox source, preparation code, Dockerfile content, environment options, workspace resources, or skills produces a new environment generation. Existing durable sessions retain their recorded sandbox state; new sessions use the current generation.
+
+## What to read next
+
+- [Subagents](/docs/subagents) explains delegation and sandbox ownership.
+- [Security model](/docs/concepts/security-model) describes the app-runtime and sandbox trust boundary.
+- [Vercel Sandbox](https://vercel.com/docs/sandbox) documents hosted sandbox behavior.

package/docs/sandbox/just-bash.mdx

@@ -0,0 +1,24 @@
+---
+title: "just-bash Sandbox"
+description: "Use a pure-JavaScript shell and virtual filesystem."
+---
+
+`JustBashSandbox.environment()` provides a shell and filesystem without starting a container or VM.
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { JustBashSandbox } from "eve/sandbox/just-bash";
+
+export const environment = JustBashSandbox.environment();
+export default defineSandbox(() => environment.open());
+```
+
+just-bash can prepare and persist its virtual filesystem. It cannot use OCI images or Dockerfiles, does not run native processes, and provides no network isolation. The session does not expose `setNetworkPolicy()`.
+
+## Automatic installation
+
+When an environment uses just-bash during `eve dev`, eve installs the package into your application if it is missing, unless you set `autoInstall: false` in the environment options. `DefaultSandbox` selects only one provider, but another environment, such as local self-modification, can use just-bash independently. Other environments require you to install the package yourself.
+
+For pnpm projects, automatic installation adds `@mongodb-js/zstd` and `node-liblzma` to `ignoredOptionalDependencies` in the owning `pnpm-workspace.yaml` when they have no explicit package policy. These optional native codecs are not needed for basic shell and filesystem operations. Commands that require those codecs may be unavailable without them. eve preserves existing package-specific build decisions and does not automatically approve build scripts.
+
+See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.

package/docs/sandbox/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Sandbox",
+  "defaultOpen": false,
+  "pages": ["index", "default", "vercel", "docker", "microsandbox", "just-bash"]
+}

package/docs/sandbox/microsandbox.mdx

@@ -0,0 +1,31 @@
+---
+title: "microsandbox"
+description: "Create local lightweight VMs from an OCI image or Dockerfile."
+---
+
+microsandbox environments use eve's default image, an existing OCI image, or `agent/sandbox/Dockerfile`.
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { MicrosandboxSandbox } from "eve/sandbox/microsandbox";
+
+export const environment = MicrosandboxSandbox.dockerfile({
+  setup: { autoInstall: false },
+});
+
+export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
+```
+
+Supported hosts are macOS on Apple Silicon and Linux with glibc and KVM.
+
+## Environment options
+
+Image, CPU, memory, pull policy, environment variables, VM setup, and `prepare` belong to the reusable environment. `eve build` builds a Dockerfile image when present, prepares a VM, and records its snapshot and image references.
+
+## Live VM options
+
+Pass `networkPolicy` to `open()`. The policy applies to the live VM, not the prepared snapshot. microsandbox accepts domain policies and credential transforms.
+
+Session creation uses the recorded snapshot and image directly. Writable VM state persists through the provider's session snapshot lifecycle.
+
+See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.

package/docs/sandbox/vercel.mdx

@@ -0,0 +1,106 @@
+---
+title: "Vercel Sandbox"
+description: "Create snapshot-backed persistent sandboxes on Vercel."
+---
+
+`VercelSandbox.environment()` prepares a reusable Vercel Sandbox snapshot and creates persistent session sandboxes from its recorded snapshot ID.
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { VercelSandbox } from "eve/sandbox/vercel";
+
+export const environment = VercelSandbox.environment({
+  prepare: async (sandbox) => {
+    await sandbox.run({ command: "pnpm install --frozen-lockfile" });
+  },
+});
+
+export default defineSandbox(() =>
+  environment.open({
+    networkPolicy: {
+      allow: {
+        "api.github.com": [],
+      },
+    },
+    resources: { vcpus: 4 },
+  }),
+);
+```
+
+## Snapshot preparation
+
+eve creates a temporary persistent Vercel Sandbox during build, installs the base runtime, writes managed workspace and skill files, runs the authored `prepare` callback, and captures a snapshot. The build artifact records the snapshot ID.
+
+When a live session sandbox does not exist, eve creates it directly from that snapshot ID. Runtime does not need to look up the temporary template Sandbox.
+
+## Initialize after open
+
+Initialize session-specific state after `open()` and before returning the sandbox. This selector writes a configuration file into the persistent `/workspace` filesystem:
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { VercelSandbox } from "eve/sandbox/vercel";
+
+export const environment = VercelSandbox.environment();
+
+export default defineSandbox(async ({ session }) => {
+  const sandbox = await environment.open();
+  await sandbox.writeTextFile({
+    content: JSON.stringify({ sessionId: session.id, workspace: "analysis" }),
+    path: ".eve/session.json",
+  });
+  return sandbox;
+});
+```
+
+The selector runs until initialization succeeds. Later workflow steps and process restarts resume the same provider state without rerunning the selector, so the file is not rewritten at each boundary.
+
+You can also configure the live sandbox and run setup commands before returning it:
+
+```ts
+export default defineSandbox(async () => {
+  const sandbox = await environment.open();
+  await sandbox.setNetworkPolicy("deny-all");
+  const result = await sandbox.run({ command: "mkdir -p .cache/app" });
+  if (result.exitCode !== 0) throw new Error(result.stderr);
+  return sandbox;
+});
+```
+
+Use the environment's `prepare` callback for immutable setup that every new session should inherit. Use post-open initialization for state that belongs only to one durable session.
+
+## Network policy
+
+Pass the initial policy to `open()`. It applies to the new live Vercel Sandbox, not to the environment definition:
+
+```ts
+return environment.open({
+  networkPolicy: {
+    allow: {
+      "api.example.com": [
+        {
+          transform: [{ headers: { authorization: `Bearer ${token}` } }],
+        },
+      ],
+    },
+  },
+});
+```
+
+Credential transforms inject headers at the network boundary so the secret does not enter the sandbox process. The dedicated Vercel environment returns a session where `setNetworkPolicy()` is required, so you can update the policy directly after `open()` without a capability check:
+
+```ts
+const sandbox = await environment.open();
+await sandbox.setNetworkPolicy("deny-all");
+return sandbox;
+```
+
+## Live sandbox options
+
+`open()` also accepts Vercel compute resources, timeout, and Drive mounts. Configure project credentials and custom fetch behavior on the environment, not in `open()`, because resume does not reconstruct start-only options.
+
+Initialize the returned sandbox directly in `defineSandbox()`. If initialization fails, eve deletes the newly started sandbox and retries the selector on the next access. After initialization succeeds, the provider persists only immutable JSON-compatible state. If the named Vercel Sandbox later disappears, resume fails rather than recreating initialization side effects.
+
+eve owns the persistent sandbox identity and prepared snapshot source.
+
+See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.