eve 0.63.0 → 0.64.0

package/docs/guides/deployment/self-hosting.md

@@ -1,6 +1,6 @@
 ---
 title: "Self-Host eve"
-description: "Run an eve agent as a Node service with your own workflow storage, sandbox backend, and routing."
+description: "Run an eve agent as a Node service with your own workflow storage, sandbox provider, and routing."
 ---
 
 Self-host eve when you operate a Node service, container platform, or reverse proxy. You run eve’s Nitro server and choose the infrastructure that stores workflows and executes sandbox sessions.
@@ -46,11 +46,11 @@ The package must export a default factory or `createWorld()` function. Read cred
 
 See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying Workflow software development kit (SDK) abstraction.
 
-## Select a sandbox backend
+## Select a sandbox provider
 
-`defaultBackend()` selects a local sandbox backend in availability order. You can instead select Docker, microsandbox, or a custom `SandboxBackend` adapter for your container, virtual machine, or isolation service.
+The default sandbox environment selects Docker, microsandbox, or just-bash according to local availability. You can select one explicitly or implement a custom provider with `defineSandboxProvider()` for your container, virtual machine, or isolation service.
 
-Don’t select `vercel()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for backend configuration and selection order.
+Don’t select `VercelSandbox.environment()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for provider configuration and selection order.
 
 ## Configure proxy routes
 
@@ -125,4 +125,4 @@ Use these guides to secure and observe the deployed agent:
 
 - [Authentication](../auth-and-route-protection): configure the host’s route policy
 - [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
-- [Sandbox](../../sandbox): select and secure a sandbox backend
+- [Sandbox](../../sandbox): select and secure a sandbox provider

package/docs/guides/deployment/vercel.mdx

@@ -27,26 +27,24 @@ A string model ID routes requests through the [Vercel AI Gateway](https://vercel
 
 Add credentials for direct model providers, tools, and connections to the Vercel project environment. Add any signing keys or passwords required by your [route authentication policy](../auth-and-route-protection). Replace `placeholderAuth()` before a browser sends a production request.
 
-## Select the sandbox backend
+## Select the sandbox environment
 
-Leave the sandbox `backend` unset to use `defaultBackend()`. On Vercel, it selects Vercel Sandbox. You can also select the backend explicitly:
+The default environment selects Vercel Sandbox on Vercel. To select it explicitly:
 
 ```typescript
 import { defineSandbox } from "eve/sandbox";
-import { vercel } from "eve/sandbox/vercel";
+import { VercelSandbox } from "eve/sandbox/vercel";
 
-export default defineSandbox({
-  backend: vercel(),
-});
+export const environment = VercelSandbox.environment();
+export default defineSandbox(() => environment.open());
 ```
 
-See [Sandbox](../../sandbox) for resource limits, network policy, and lifecycle hooks.
+See [Sandbox](../../sandbox) for preparation, resource limits, network policy, and lifecycle.
 
 <Callout type="info" title="Sandbox prewarming">
-  During a Vercel build, eve automatically creates or reuses a sandbox template when your sandbox
-  has `bootstrap()` or seed files. The build needs permission to create Vercel Sandbox templates,
-  and a prewarm failure stops the deployment. See the [sandbox lifecycle](../../sandbox#lifecycle)
-  for template and session setup.
+  During a Vercel build, eve creates or reuses a snapshot-backed template when an environment uses
+  `VercelSandbox.environment({prepare})` or has seed files. A prewarm failure stops the deployment.
+  See the [sandbox lifecycle](../../sandbox#lifecycle).
 </Callout>
 
 ## Deploy the agent
@@ -137,7 +135,7 @@ Vercel uses the generated output to configure these services:
 - **Web runtime**: serves health, session, stream, channel, callback, and schedule routes
 - **Vercel Workflow**: persists and resumes durable runs, with optimistic replay preconditions enabled so stale event-log snapshots reload before they can commit
 - **Vercel Cron**: invokes authored schedules
-- **Vercel Sandbox**: runs sandbox sessions selected by `defaultBackend()`
+- **Vercel Sandbox**: runs sandbox sessions selected by the default sandbox environment
 
 ## Verify the deployment
 

package/docs/guides/dev-tui.md

@@ -71,7 +71,7 @@ Changes apply together after the final choice, then the picker returns to chat.
 
 A successful login or model change takes effect on the next prompt.
 
-OpenAI, ChatGPT, and Gateway connections default to `gpt-5.6-luna-fast`; Anthropic defaults to `claude-sonnet-5`. An explicitly authored compatible model stays selected. If a new default is unavailable, eve offers the connection's available models. Dynamic or custom model expressions must be edited in `agent.ts`.
+Gateway connections default to `spacexai/grok-4.7`; OpenAI and ChatGPT default to `gpt-5.6-luna-fast`; Anthropic defaults to `claude-sonnet-5`. An explicitly authored compatible model stays selected. If a new default is unavailable, eve offers the connection's available models. Dynamic or custom model expressions must be edited in `agent.ts`.
 
 ## Add an integration
 

package/docs/guides/hooks.md

@@ -86,6 +86,10 @@ handle can also automatically resume on later I/O. A hook failure, including a
 failed stop, follows the normal
 [hook failure behavior](#what-happens-when-a-hook-throws).
 
+For `subagent.called` and `subagent.completed`, `ctx.session.id` identifies the
+parent session. Typed handlers and `*` handlers receive this context even when
+the subagent event arrives between parent turns.
+
 ### Narrowing tool results
 
 `toolResultFrom` narrows an `action.result` event to a specific authored tool or MCP connection and returns typed output. Import it from `eve/tools`:

package/docs/memory/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Memory",
   "defaultOpen": false,
-  "pages": ["overview", "file", "custom-provider"]
+  "pages": ["overview", "file", "../patterns/multi-tenant-memory", "custom-provider"]
 }

package/docs/memory/overview.mdx

@@ -28,6 +28,10 @@ caller using the built-in file provider. Swap `provider` for
 [Supermemory](#supermemory), [Upstash AgentKit](#upstash-agentkit), or your own
 implementation and the rest of the definition stays the same.
 
+For an application with multiple tenants, follow the
+[Multi-tenant memory](/docs/patterns/multi-tenant-memory) guide to scope memory
+by authenticated tenant and caller.
+
 ## How a memory slot works
 
 A memory slot is the unit eve manages. Each slot binds one provider to an

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,7 +136,7 @@ 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/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
@@ -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,216 @@
+---
+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.
+
+At runtime, eve passes the recorded artifact directly to the provider when it creates a live sandbox. 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,18 @@
+---
+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()`.
+
+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.