From fff1d3b4dd777d17747836f792ef7f734507834b Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Tue, 3 Nov 2026 15:29:29 +0700
Subject: [PATCH 1/7] fix(ai-sandbox-cloudflare): run each command in a
 subshell so exit cannot end the session

---
 .changeset/cloudflare-exec-subshell.md        |  5 +++++
 packages/ai-sandbox-cloudflare/src/handle.ts  | 14 ++++++++++--
 .../tests/handle.test.ts                      | 22 ++++++++++++++++++-
 3 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/cloudflare-exec-subshell.md

diff --git a/.changeset/cloudflare-exec-subshell.md b/.changeset/cloudflare-exec-subshell.md
new file mode 100644
index 0000000000..84246415e0
--- /dev/null
+++ b/.changeset/cloudflare-exec-subshell.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-sandbox-cloudflare': patch
+---
+
+Run each `exec` and `spawn` command in a subshell. Cloudflare runs every command in one shared shell session, so a command that called `exit` ended the session and every later command failed. This broke the `@tanstack/ai-computer-sandbox` driver on Cloudflare.
diff --git a/packages/ai-sandbox-cloudflare/src/handle.ts b/packages/ai-sandbox-cloudflare/src/handle.ts
index 97e69595c7..6de70cdc68 100644
--- a/packages/ai-sandbox-cloudflare/src/handle.ts
+++ b/packages/ai-sandbox-cloudflare/src/handle.ts
@@ -59,6 +59,16 @@ function q(value: string): string {
 
 const LSTAT_MISSING = '__TANSTACK_LSTAT_MISSING__'
 
+/**
+ * Cloudflare runs every command in one long-lived shell session, so a bare
+ * `exit` ends the session and every later command fails. A subshell keeps
+ * `exit`, `cd`, and variables local to the command, like the other providers.
+ * The newlines keep a trailing `#` comment or heredoc from eating the `)`.
+ */
+function subshell(command: string) {
+  return `(\n${command}\n)`
+}
+
 /** Verify a missing path by listing parent entries. `test -e` also fails for inaccessible parents. */
 function lstatCommand(path: string): string {
   return `tanstack_lstat_path=${q(path)}; tanstack_lstat_output=$(stat -c '%f:%s' -- "$tanstack_lstat_path" 2>&1); tanstack_lstat_status=$?; if [ "$tanstack_lstat_status" -eq 0 ]; then printf '%s\n' "$tanstack_lstat_output"; else tanstack_lstat_missing() { tanstack_missing_path=$1; case "$tanstack_missing_path" in /|.) return 1 ;; */*) tanstack_parent=${'$'}{tanstack_missing_path%/*}; tanstack_name=${'$'}{tanstack_missing_path##*/}; [ -n "$tanstack_parent" ] || tanstack_parent=/ ;; *) tanstack_parent=.; tanstack_name=$tanstack_missing_path ;; esac; tanstack_parent_mode=$(stat -L -c '%f' -- "$tanstack_parent" 2>/dev/null); tanstack_parent_status=$?; if [ "$tanstack_parent_status" -ne 0 ]; then tanstack_lstat_missing "$tanstack_parent"; else case "$tanstack_parent_mode" in 4[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]) case "$tanstack_parent" in /*) tanstack_find_parent=$tanstack_parent ;; *) tanstack_find_parent=./$tanstack_parent ;; esac; tanstack_match=$(find -H "$tanstack_find_parent" -mindepth 1 -maxdepth 1 -exec sh -c 'tanstack_target=$1; shift; for tanstack_candidate do [ "${'$'}{tanstack_candidate##*/}" = "$tanstack_target" ] && { printf 1; exit 0; }; done; exit 0' sh "$tanstack_name" '{}' + 2>/dev/null); tanstack_find_status=$?; [ "$tanstack_find_status" -eq 0 ] && [ -z "$tanstack_match" ] ;; *) return 1 ;; esac; fi; }; if tanstack_lstat_missing "$tanstack_lstat_path"; then printf '%s' '${LSTAT_MISSING}'; else printf '%s\n' "$tanstack_lstat_output" >&2; exit "$tanstack_lstat_status"; fi; fi`
@@ -248,7 +258,7 @@ export class CloudflareHandle implements SandboxHandle {
     command: string,
     opts?: ProcessOptions,
   ): Promise<ExecResult> {
-    const result = await this.sandbox.exec(command, {
+    const result = await this.sandbox.exec(subshell(command), {
       ...(opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir }),
       ...(opts?.env ? { env: opts.env } : {}),
     })
@@ -282,7 +292,7 @@ export class CloudflareHandle implements SandboxHandle {
     // before the command runs. Mid-run cancellation is therefore unavailable
     // on this provider; a stuck run is bounded by the coordinator's watchdog
     // and the Durable Object lifecycle instead. `kill()` is a best-effort no-op.
-    const settled = this.sandbox.exec(command, {
+    const settled = this.sandbox.exec(subshell(command), {
       ...(opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir }),
       ...(opts?.env ? { env: opts.env } : {}),
       stream: true,
diff --git a/packages/ai-sandbox-cloudflare/tests/handle.test.ts b/packages/ai-sandbox-cloudflare/tests/handle.test.ts
index 089e3d90a4..7501350cdc 100644
--- a/packages/ai-sandbox-cloudflare/tests/handle.test.ts
+++ b/packages/ai-sandbox-cloudflare/tests/handle.test.ts
@@ -64,7 +64,9 @@ function sandboxFixture(methods: SandboxFixtureMethods): Sandbox {
 function mockSandbox(): { sandbox: Sandbox; files: Map<string, string> } {
   const files = new Map<string, string>()
 
-  const exec = (command: string, opts?: MockExecOpts): Promise<ExecResult> => {
+  const exec = (wrapped: string, opts?: MockExecOpts): Promise<ExecResult> => {
+    // The handle runs each command in a subshell. Match the inner command.
+    const command = wrapped.replace(/^\(\n([\s\S]*)\n\)$/, '$1')
     const ok = (stdout = ''): ExecResult => ({
       stdout,
       stderr: '',
@@ -358,6 +360,24 @@ describe('CloudflareHandle', () => {
     expect(r.exitCode).toBe(0)
   })
 
+  it('runs each command in a subshell, so exit cannot end the shared session', async () => {
+    const commands: Array<string> = []
+    const sandbox = sandboxFixture({
+      exec: (command: string) => {
+        commands.push(command)
+        return Promise.resolve({ stdout: '', stderr: '', exitCode: 3 })
+      },
+      setEnvVars: () => Promise.resolve(),
+      exposePort: (port: number) =>
+        Promise.resolve({ url: `https://${port}.example.workers.dev` }),
+      destroy: () => Promise.resolve(),
+    })
+    const handle = new CloudflareHandle('sbx-1', sandbox, '/workspace')
+    await handle.process.exec('exit 3 # done')
+    await (await handle.process.spawn('exit 3')).wait()
+    expect(commands).toEqual(['(\nexit 3 # done\n)', '(\nexit 3\n)'])
+  })
+
   it('spawn streams output via the queue and resolves wait()', async () => {
     const handle = createLstatHandle()
     const proc = await handle.process.spawn('run something')

From 305457da37f6165b0e44bb356dbfbd61cde6dfee Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Tue, 3 Nov 2026 16:24:17 +0700
Subject: [PATCH 2/7] feat(ai-computer-sandbox): keep each thread's sandbox and
 reconnect to it with sandboxIds

---
 .changeset/computer-sandbox-keep-desktop.md   |  5 ++
 docs/computer-use/drivers.md                  | 50 ++++++++++++++++-
 packages/ai-computer-sandbox/README.md        | 19 +++++++
 packages/ai-computer-sandbox/src/driver.ts    | 55 +++++++++++++++----
 .../ai-computer-sandbox/tests/driver.test.ts  | 46 +++++++++++++++-
 5 files changed, 163 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/computer-sandbox-keep-desktop.md

diff --git a/.changeset/computer-sandbox-keep-desktop.md b/.changeset/computer-sandbox-keep-desktop.md
new file mode 100644
index 0000000000..31ef1099dd
--- /dev/null
+++ b/.changeset/computer-sandbox-keep-desktop.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-computer-sandbox': minor
+---
+
+Add the `sandboxIds` option to `sandboxComputer()`. It keeps the sandbox of each thread and reconnects to it later with `provider.resume`, so a user who comes back to a thread gets the same desktop. A kept sandbox is not destroyed when its thread closes or goes idle.
diff --git a/docs/computer-use/drivers.md b/docs/computer-use/drivers.md
index 1a93bf5c23..7f4ee94679 100644
--- a/docs/computer-use/drivers.md
+++ b/docs/computer-use/drivers.md
@@ -130,11 +130,12 @@ const computerUse = createComputerUse({
 
 - `provider`: the sandbox provider. It makes one sandbox for each thread.
 - `display`: the screen size of each desktop in pixels. The default is 1024 x 768.
+- `sandboxIds`: keep the desktop of each thread and reconnect to it later. See [Keep the desktop for later](#keep-the-desktop-for-later).
 
 How the sandbox driver behaves:
 
 - There is no `navigate` tool, because a desktop has no address. The model opens the browser on the desktop.
-- When a thread closes or goes idle, `createComputerUse` destroys its sandbox.
+- When a thread closes or goes idle, `createComputerUse` destroys its sandbox, unless you set `sandboxIds`.
 - One scroll step is 100 pixels.
 - The driver quotes every key name and all typed text before they go to the shell.
 
@@ -155,6 +156,53 @@ RUN apt-get update && apt-get install -y xvfb xdotool scrot x11-utils
 
 If a tool is missing, the driver throws an error with its name.
 
+### Keep the desktop for later
+
+Give `sandboxComputer()` a `sandboxIds` store. A user who comes back to a thread a day later gets the same desktop, for example with the browser still signed in.
+
+1. Store one sandbox id for each thread, next to your threads.
+2. Set the provider to pause the sandbox, not to kill it. With E2B, use `onTimeout: 'pause'`.
+
+```ts
+import { createComputerUse } from '@tanstack/ai-computer-use'
+import { sandboxComputer } from '@tanstack/ai-computer-sandbox'
+import { e2bSandbox } from '@tanstack/ai-sandbox-e2b'
+
+declare const db: {
+  getSandboxId: (threadId: string) => Promise<string | undefined>
+  setSandboxId: (threadId: string, sandboxId: string) => Promise<void>
+}
+
+const computerUse = createComputerUse({
+  driver: sandboxComputer({
+    provider: e2bSandbox({
+      template: 'desktop',
+      timeoutMs: 15 * 60_000,
+      onTimeout: 'pause',
+    }),
+    sandboxIds: {
+      get: (threadId) => db.getSandboxId(threadId),
+      set: (threadId, sandboxId) => db.setSandboxId(threadId, sandboxId),
+    },
+  }),
+})
+```
+
+With `sandboxIds`, the driver works like this:
+
+- The first call of a thread creates a sandbox and stores its id.
+- A later call reconnects to that sandbox with `provider.resume`. If the sandbox is gone, the driver creates a new one and stores the new id.
+- The driver never destroys a kept sandbox. The provider timeout pauses or removes it.
+- If the setup of a reconnected sandbox fails, the driver keeps the sandbox and throws the error. The next call tries again.
+
+What each provider keeps:
+
+- E2B with `onTimeout: 'pause'` keeps the memory and the disk. Open apps come back as they were.
+- Docker keeps the container. A stopped container starts again with its disk, and the driver starts the display again.
+
+> [!WARNING]
+> A kept desktop holds what the user did in it, like signed-in browser sessions. Delete the sandbox when the user deletes the thread.
+
 Do you already have a desktop sandbox? See [Share one sandbox](#share-one-sandbox).
 
 ## Your own computer
diff --git a/packages/ai-computer-sandbox/README.md b/packages/ai-computer-sandbox/README.md
index dadacba3e3..0550f18baa 100644
--- a/packages/ai-computer-sandbox/README.md
+++ b/packages/ai-computer-sandbox/README.md
@@ -66,6 +66,25 @@ RUN apt-get update && apt-get install -y xvfb xdotool scrot x11-utils
 
 When a tool is missing, the driver throws an error with its name.
 
+## Keep the desktop for later
+
+Give `sandboxComputer()` a `sandboxIds` store, and set the provider to pause the sandbox. A user who comes back to a thread later gets the same desktop.
+
+```typescript
+const computerUse = createComputerUse({
+  driver: sandboxComputer({
+    provider: e2bSandbox({ template: 'desktop', onTimeout: 'pause' }),
+    sandboxIds: {
+      get: (threadId) => db.getSandboxId(threadId),
+      set: (threadId, sandboxId) => db.setSandboxId(threadId, sandboxId),
+    },
+  }),
+})
+```
+
+- A later call of the thread reconnects with `provider.resume`. If the sandbox is gone, the driver creates a new one and stores its id.
+- The driver never destroys a kept sandbox. The provider timeout pauses or removes it.
+
 ## Share one sandbox
 
 To drive a sandbox that you already have, use `createSandboxComputerDriver`. Every thread shares this sandbox, so it serves one conversation at a time.
diff --git a/packages/ai-computer-sandbox/src/driver.ts b/packages/ai-computer-sandbox/src/driver.ts
index 1c4dcafbba..aa7cfe71ca 100644
--- a/packages/ai-computer-sandbox/src/driver.ts
+++ b/packages/ai-computer-sandbox/src/driver.ts
@@ -24,6 +24,16 @@ export interface SandboxComputerOptions {
   provider: SandboxProvider
   /** The screen size in pixels. The default is `{ width: 1024, height: 768 }`. */
   display?: { width: number; height: number }
+  /**
+   * Keep the sandbox of each thread, and reconnect to it later. Store the ids
+   * where your threads persist. With this option, the driver does not destroy
+   * a sandbox when its thread closes or goes idle. The provider timeout
+   * pauses or removes it, like E2B `onTimeout: 'pause'`.
+   */
+  sandboxIds?: {
+    get: (threadId: string) => Promise<string | undefined>
+    set: (threadId: string, sandboxId: string) => Promise<void>
+  }
 }
 
 const DEFAULT_DISPLAY = { width: 1024, height: 768 }
@@ -234,7 +244,8 @@ export async function createSandboxComputerDriver({
  *
  * Each sandbox comes from `provider.create`. When `createComputerUse` closes
  * a thread, or the thread goes idle, the sandbox of that thread is
- * destroyed. The drivers have `cursorPosition`. They have no `zoom` and no
+ * destroyed. With `sandboxIds`, the sandbox is kept, and the next call of the
+ * thread reconnects to it with `provider.resume`. The drivers have `cursorPosition`. They have no `zoom` and no
  * `navigate`, because a desktop has no address. The model opens the browser
  * on the desktop.
  *
@@ -248,13 +259,29 @@ export async function createSandboxComputerDriver({
 export function sandboxComputer({
   provider,
   display = DEFAULT_DISPLAY,
+  sandboxIds,
 }: SandboxComputerOptions) {
+  /** The sandbox of the thread: its stored sandbox, when it still exists, or a new one. */
+  async function open(threadId: string) {
+    const id = await sandboxIds?.get(threadId)
+    const resumed = id === undefined ? null : await provider.resume({ id })
+    if (resumed) return { sandbox: resumed, isNew: false }
+    const sandbox = await provider.create({})
+    try {
+      await sandboxIds?.set(threadId, sandbox.id)
+    } catch (error) {
+      await destroyAfterFailure(sandbox)
+      throw error
+    }
+    return { sandbox, isNew: true }
+  }
+
   const factory: ComputerDriverFactory = {
     display,
     environment: 'linux',
     capabilities: { zoom: false, cursorPosition: true, navigate: false },
-    async create() {
-      const sandbox = await provider.create({})
+    async create({ threadId }) {
+      const { sandbox, isNew } = await open(threadId)
       try {
         const driver = await createSandboxComputerDriver({ sandbox, display })
         const { width, height } = driver.display
@@ -263,18 +290,26 @@ export function sandboxComputer({
             `The sandbox display is ${width}x${height}, not ${display.width}x${display.height}. Set display to the size of the running display.`,
           )
         }
+        // A kept sandbox outlives its thread. The provider timeout ends it.
+        if (sandboxIds) return driver
         return { ...driver, close: () => sandbox.destroy() }
       } catch (error) {
-        // Keep the setup error. A failed destroy does not replace it.
-        await sandbox.destroy().catch((destroyError: unknown) => {
-          console.error(
-            'Failed to destroy the sandbox after setup failed.',
-            destroyError,
-          )
-        })
+        // A kept sandbox holds the state of the thread, like a signed-in
+        // browser. Keep it, so the next call of the thread tries it again.
+        if (isNew) await destroyAfterFailure(sandbox)
         throw error
       }
     },
   }
   return factory
 }
+
+/** Destroy a sandbox after a setup error. A failed destroy does not replace that error. */
+async function destroyAfterFailure(sandbox: SandboxHandle) {
+  await sandbox.destroy().catch((destroyError: unknown) => {
+    console.error(
+      'Failed to destroy the sandbox after setup failed.',
+      destroyError,
+    )
+  })
+}
diff --git a/packages/ai-computer-sandbox/tests/driver.test.ts b/packages/ai-computer-sandbox/tests/driver.test.ts
index f656121d49..785773d5f7 100644
--- a/packages/ai-computer-sandbox/tests/driver.test.ts
+++ b/packages/ai-computer-sandbox/tests/driver.test.ts
@@ -20,6 +20,8 @@ interface FakeOptions {
   size?: string
 }
 
+let sandboxCount = 0
+
 /** A fake sandbox. Each command adds one line to `calls`, prefixed with `exec` or `spawn`. */
 function fakeSandbox({ running = true, missing = [], size }: FakeOptions = {}) {
   const calls: Array<string> = []
@@ -49,6 +51,7 @@ function fakeSandbox({ running = true, missing = [], size }: FakeOptions = {}) {
     calls.push('destroy')
   })
   const sandbox = {
+    id: `sbx-${++sandboxCount}`,
     process: { exec, spawn },
     destroy,
   } as unknown as SandboxHandle
@@ -63,7 +66,11 @@ async function setup() {
   return { driver, calls: fake.calls }
 }
 
-function fakeProvider(fakes: Array<ReturnType<typeof fakeSandbox>>) {
+/** A provider that hands out `fakes` in order, and resumes only the `alive` sandboxes. */
+function fakeProvider(
+  fakes: Array<ReturnType<typeof fakeSandbox>>,
+  alive: Array<ReturnType<typeof fakeSandbox>> = [],
+) {
   let next = 0
   const provider = {
     name: 'fake',
@@ -72,10 +79,26 @@ function fakeProvider(fakes: Array<ReturnType<typeof fakeSandbox>>) {
       if (!fake) throw new Error('no more sandboxes')
       return fake.sandbox
     }),
+    resume: vi.fn(
+      async ({ id }: { id: string }) =>
+        alive.find((fake) => fake.sandbox.id === id)?.sandbox ?? null,
+    ),
   } as unknown as SandboxProvider
   return provider
 }
 
+/** An in-memory `sandboxIds` store. */
+function memoryIds(initial: Record<string, string> = {}) {
+  const ids = new Map(Object.entries(initial))
+  return {
+    ids,
+    get: async (threadId: string) => ids.get(threadId),
+    set: async (threadId: string, sandboxId: string) => {
+      ids.set(threadId, sandboxId)
+    },
+  }
+}
+
 describe('createSandboxComputerDriver', () => {
   it('uses a display that already runs and reports linux', async () => {
     const { sandbox, calls } = fakeSandbox()
@@ -283,4 +306,25 @@ describe('sandboxComputer', () => {
     )
     error.mockRestore()
   })
+
+  it('with sandboxIds, resumes the stored sandbox and never destroys it', async () => {
+    const kept = fakeSandbox()
+    const provider = fakeProvider([], [kept])
+    const sandboxIds = memoryIds({ a: kept.sandbox.id })
+    const factory = sandboxComputer({ provider, sandboxIds })
+    const driver = await factory.create({ threadId: 'a' })
+    expect(provider.create).not.toHaveBeenCalled()
+    expect(driver.close).toBeUndefined()
+    expect(kept.destroy).not.toHaveBeenCalled()
+  })
+
+  it('with sandboxIds, creates and stores a sandbox when the stored one is gone', async () => {
+    const created = fakeSandbox()
+    const provider = fakeProvider([created])
+    const sandboxIds = memoryIds({ a: 'gone' })
+    const factory = sandboxComputer({ provider, sandboxIds })
+    await factory.create({ threadId: 'a' })
+    expect(provider.resume).toHaveBeenCalledWith({ id: 'gone' })
+    expect(sandboxIds.ids.get('a')).toBe(created.sandbox.id)
+  })
 })

From 7a3d8fd6c0c86c24192455176b80ac677915b9aa Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Tue, 3 Nov 2026 16:24:18 +0700
Subject: [PATCH 3/7] feat(examples): computer use sign-in example where the
 model never sees the password

---
 docs/config.json                              |  16 +-
 docs/getting-started/overview.md              |   1 +
 docs/tutorials/computer-use-login.md          | 490 ++++++++++++++++++
 docs/tutorials/computer-use.md                |   2 +
 examples/README.md                            |  20 +
 .../react/computer-use-login/.env.example     |   3 +
 examples/react/computer-use-login/.gitignore  |   8 +
 examples/react/computer-use-login/README.md   |  62 +++
 .../react/computer-use-login/package.json     |  37 ++
 .../computer-use-login/sandbox/Dockerfile     |  18 +
 .../computer-use-login/sandbox/desktop.sh     |  19 +
 .../react/computer-use-login/sandbox/login.py | 143 +++++
 .../computer-use-login/sandbox/policy.json    |   6 +
 .../react/computer-use-login/src/harness.ts   | 167 ++++++
 .../computer-use-login/src/request-login.ts   |  20 +
 .../computer-use-login/src/routeTree.gen.ts   | 104 ++++
 .../react/computer-use-login/src/router.tsx   |  10 +
 .../computer-use-login/src/routes/__root.tsx  |  41 ++
 .../src/routes/api.harness.$.ts               |  12 +
 .../src/routes/api.login.ts                   |  25 +
 .../computer-use-login/src/routes/index.tsx   | 316 +++++++++++
 .../react/computer-use-login/src/styles.css   |  10 +
 .../react/computer-use-login/tsconfig.json    |  25 +
 .../react/computer-use-login/vite.config.ts   |  26 +
 pnpm-lock.yaml                                |  70 +++
 25 files changed, 1648 insertions(+), 3 deletions(-)
 create mode 100644 docs/tutorials/computer-use-login.md
 create mode 100644 examples/react/computer-use-login/.env.example
 create mode 100644 examples/react/computer-use-login/.gitignore
 create mode 100644 examples/react/computer-use-login/README.md
 create mode 100644 examples/react/computer-use-login/package.json
 create mode 100644 examples/react/computer-use-login/sandbox/Dockerfile
 create mode 100644 examples/react/computer-use-login/sandbox/desktop.sh
 create mode 100644 examples/react/computer-use-login/sandbox/login.py
 create mode 100644 examples/react/computer-use-login/sandbox/policy.json
 create mode 100644 examples/react/computer-use-login/src/harness.ts
 create mode 100644 examples/react/computer-use-login/src/request-login.ts
 create mode 100644 examples/react/computer-use-login/src/routeTree.gen.ts
 create mode 100644 examples/react/computer-use-login/src/router.tsx
 create mode 100644 examples/react/computer-use-login/src/routes/__root.tsx
 create mode 100644 examples/react/computer-use-login/src/routes/api.harness.$.ts
 create mode 100644 examples/react/computer-use-login/src/routes/api.login.ts
 create mode 100644 examples/react/computer-use-login/src/routes/index.tsx
 create mode 100644 examples/react/computer-use-login/src/styles.css
 create mode 100644 examples/react/computer-use-login/tsconfig.json
 create mode 100644 examples/react/computer-use-login/vite.config.ts

diff --git a/docs/config.json b/docs/config.json
index 5ebdf1256b..ad5c530a82 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -13,7 +13,7 @@
           "label": "Overview",
           "to": "getting-started/overview",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-10-22"
+          "updatedAt": "2026-11-03"
         },
         {
           "label": "Quick Start",
@@ -98,7 +98,12 @@
           "label": "Computer Use",
           "to": "tutorials/computer-use",
           "addedAt": "2026-10-21",
-          "updatedAt": "2026-10-22"
+          "updatedAt": "2026-11-03"
+        },
+        {
+          "label": "Sign In Without the Model",
+          "to": "tutorials/computer-use-login",
+          "addedAt": "2026-11-03"
         },
         {
           "label": "Subscribe to MCP Events",
@@ -151,6 +156,11 @@
           "to": "framework/react/examples/computer-use",
           "addedAt": "2026-10-21"
         },
+        {
+          "label": "Computer Use Login",
+          "to": "framework/react/examples/computer-use-login",
+          "addedAt": "2026-11-03"
+        },
         {
           "label": "MCP Events",
           "to": "framework/react/examples/mcp-events",
@@ -1049,7 +1059,7 @@
           "label": "Drivers",
           "to": "computer-use/drivers",
           "addedAt": "2026-10-20",
-          "updatedAt": "2026-10-22"
+          "updatedAt": "2026-11-03"
         },
         {
           "label": "Safety Checks",
diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
index a6a08355d6..5592add865 100644
--- a/docs/getting-started/overview.md
+++ b/docs/getting-started/overview.md
@@ -90,6 +90,7 @@ Each tutorial builds one small app from start to finish:
 - [Subagents](../tutorials/subagents): a researcher, an SEO agent, and a writer in one blog-writing chat.
 - [Build an MCP Server](../tutorials/mcp-server): serve a tool, a resource, and a prompt.
 - [Computer Use](../tutorials/computer-use): let the model use a web page from screenshots.
+- [Sign In Without the Model](../tutorials/computer-use-login): let the model sign in to a site, and keep the password away from it.
 
 ## Reference
 
diff --git a/docs/tutorials/computer-use-login.md b/docs/tutorials/computer-use-login.md
new file mode 100644
index 0000000000..7080698223
--- /dev/null
+++ b/docs/tutorials/computer-use-login.md
@@ -0,0 +1,490 @@
+---
+title: Sign In Without the Model
+id: computer-use-login
+order: 9
+description: "Let a computer use agent sign in to a site, and keep the password away from the model. The user types the password in a card, and the server fills the form in a Docker desktop."
+keywords:
+  - tanstack ai
+  - tutorial
+  - computer use
+  - sign in
+  - password
+  - requestLogin
+  - sandboxComputer
+  - docker
+  - harness
+---
+
+Give the model a `requestLogin` tool with `needsApproval: true`. When a page asks for a password, the run stops and your chat shows a login card. The server fills the form in the browser, so the model never sees the password.
+
+This tutorial uses React, TanStack Start, the harness, OpenAI, and a Docker desktop with Chromium. It takes about 30 minutes. Start Docker before you begin.
+
+## 1. Create a Start app
+
+```bash
+npx @tanstack/cli@latest create
+```
+
+Pick React. Then install the packages:
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai @tanstack/ai-react @tanstack/ai-openai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-computer-use @tanstack/ai-computer-sandbox @tanstack/ai-sandbox-docker zod
+
+<!-- ::end:tabs -->
+
+Put your OpenAI key in `.env.local`:
+
+```bash
+OPENAI_API_KEY=sk-...
+```
+
+## Client and server
+
+- The **desktop** is a Docker container with a screen and Chromium. Each chat thread gets its own container.
+- The **server** runs the harness. The model clicks and types on the desktop with the `computer` tool. The `requestLogin` tool fills the sign-in form.
+- The **client** shows the chat and the login card. It sends the password to its own route, not to the chat.
+
+The approval of a tool call goes into the harness log. So the card approves the call with only "yes", and the password takes another path.
+
+## 2. Build the desktop
+
+Create a `sandbox` folder in your app with four files.
+
+`sandbox/Dockerfile` installs the screen, the tools of the sandbox computer driver, Chromium, and Python:
+
+```dockerfile
+FROM debian:bookworm-slim
+
+RUN printf 'Acquire::Retries "10";\nAcquire::ForceIPv4 "true";\n' > /etc/apt/apt.conf.d/80retries \
+  && apt-get update \
+  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    xvfb xdotool scrot x11-utils chromium fonts-dejavu-core \
+    python3 python3-websockets ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY policy.json /etc/chromium/policies/managed/policy.json
+COPY desktop.sh login.py /opt/desktop/
+RUN chmod +x /opt/desktop/desktop.sh
+```
+
+`sandbox/policy.json` keeps passwords off the screen. The model sees the screen and moves the mouse, so Chromium must not offer to show a saved password:
+
+```json
+{
+  "PasswordManagerEnabled": false,
+  "AutofillAddressEnabled": false,
+  "AutofillCreditCardEnabled": false,
+  "URLBlocklist": ["javascript://*"]
+}
+```
+
+`sandbox/desktop.sh` is the main process of the container. It starts the screen and Chromium:
+
+```bash
+#!/bin/sh
+rm -f /tmp/.X0-lock
+Xvfb :0 -ac -screen 0 1024x768x24 -nolisten tcp &
+until DISPLAY=:0 xdpyinfo >/dev/null 2>&1; do sleep 0.2; done
+
+while true; do
+  # --no-sandbox: Chromium runs as root in the container, which is the sandbox.
+  DISPLAY=:0 chromium --no-sandbox --test-type --no-first-run \
+    --no-default-browser-check --disable-dev-shm-usage \
+    --user-data-dir=/root/chromium-profile \
+    --remote-debugging-port=9222 \
+    --window-position=0,0 --window-size=1024,768 about:blank
+  sleep 1
+done
+```
+
+- `--user-data-dir` keeps the cookies. A restarted container is still signed in.
+- `--remote-debugging-port` listens on 127.0.0.1 inside the container only. No port leaves the container.
+
+`sandbox/login.py` signs in. Copy it from the [example](https://github.com/TanStack/ai/blob/main/examples/react/computer-use-login/sandbox/login.py). It reads the site, the username, and the password from its environment, then talks to Chromium over the debugging port:
+
+1. It opens the site in the current tab.
+2. It stops if the page is not on the origin of the site, so a redirect cannot get the password.
+3. It fills the username field and the password field, then submits the form.
+4. It clears every password field, and prints the address of the page.
+
+Build the image:
+
+```bash
+docker build -t computer-use-login-desktop sandbox
+```
+
+## 3. Share the tool definition
+
+The server and the browser both import the tool definition. Create `src/request-login.ts`:
+
+```typescript ignore
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+export const requestLoginTool = toolDefinition({
+  name: 'requestLogin',
+  description:
+    'Ask the user to sign in to a site. The user types the username and password in a form that you never see, and the server fills the sign-in form in the browser. Call it when a page asks for a password. Pass the address of the sign-in page.',
+  // The run stops until the user answers the login card.
+  needsApproval: true,
+  inputSchema: z.object({
+    site: z
+      .url({ protocol: /^https?$/ })
+      .describe(
+        'The address of the sign-in page, for example https://example.com/login',
+      ),
+  }),
+})
+```
+
+## 4. Set up the harness
+
+Create `src/harness.ts`. It has the Docker provider, two stores, the tool, and the harness.
+
+First the provider and the sandbox ids. `sandboxIds` keeps the container of each thread, so the thread finds its signed-in browser again later:
+
+```typescript ignore
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { createHarnessHandler } from '@tanstack/ai-harness/server'
+import { computerUse } from '@tanstack/ai-computer-use/harness'
+import { sandboxComputer } from '@tanstack/ai-computer-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+import { openaiText } from '@tanstack/ai-openai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+import { requestLoginTool } from './request-login'
+
+const provider = dockerSandbox({
+  image: 'computer-use-login-desktop',
+  keepAliveCommand: ['/opt/desktop/desktop.sh'],
+})
+
+// The container id of each thread, in a file.
+const SANDBOX_IDS_FILE = resolve('.data/sandbox-ids.json')
+const sandboxIdsSchema = z.record(z.string(), z.string())
+let sandboxIdsWrite: Promise<void> = Promise.resolve()
+
+async function readSandboxIds() {
+  try {
+    return sandboxIdsSchema.parse(
+      JSON.parse(await readFile(SANDBOX_IDS_FILE, 'utf8')),
+    )
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return {}
+    }
+    throw error
+  }
+}
+
+const sandboxIds = {
+  get: async (threadId: string) => (await readSandboxIds())[threadId],
+  set: (threadId: string, sandboxId: string) => {
+    // One write at a time, so two threads do not lose each other's id.
+    sandboxIdsWrite = sandboxIdsWrite.then(async () => {
+      const ids = await readSandboxIds()
+      await mkdir(dirname(SANDBOX_IDS_FILE), { recursive: true })
+      await writeFile(
+        SANDBOX_IDS_FILE,
+        JSON.stringify({ ...ids, [threadId]: sandboxId }),
+      )
+    })
+    return sandboxIdsWrite
+  },
+}
+```
+
+Then the logins. The card sends a login, and the tool takes it once. A login that nobody takes is deleted after 5 minutes:
+
+```typescript ignore
+const LOGIN_TTL_MS = 5 * 60_000
+const logins = new Map<
+  string,
+  {
+    site: string
+    username: string
+    password: string
+    timer: ReturnType<typeof setTimeout>
+  }
+>()
+
+export const loginSchema = z.object({
+  threadId: z.string().min(1).max(200),
+  site: z.url({ protocol: /^https?$/ }).max(2000),
+  username: z.string().min(1).max(500),
+  password: z.string().min(1).max(500),
+})
+
+export function saveLogin({ threadId, ...login }: z.infer<typeof loginSchema>) {
+  clearTimeout(logins.get(threadId)?.timer)
+  const timer = setTimeout(() => logins.delete(threadId), LOGIN_TTL_MS)
+  timer.unref()
+  logins.set(threadId, { ...login, timer })
+}
+
+function takeLogin(threadId: string, site: string) {
+  const login = logins.get(threadId)
+  logins.delete(threadId)
+  clearTimeout(login?.timer)
+  if (!login) {
+    throw new Error(
+      'The user gave no username and password. Call requestLogin again.',
+    )
+  }
+  if (new URL(login.site).origin !== new URL(site).origin) {
+    throw new Error(
+      `The user signed in for ${new URL(login.site).origin}, not ${new URL(site).origin}.`,
+    )
+  }
+  return login
+}
+```
+
+Then the tool. It runs after the user approves the card:
+
+```typescript ignore
+const loginResultSchema = z.object({
+  url: z.string(),
+  hasPasswordField: z.boolean(),
+})
+
+const requestLogin = requestLoginTool.server(async ({ site }, context) => {
+  const threadId = context?.threadId
+  if (!threadId) throw new Error('requestLogin runs only in a chat thread.')
+  const login = takeLogin(threadId, site)
+
+  // The user can answer the card hours later. `resume` starts a stopped
+  // container again.
+  const id = await sandboxIds.get(threadId)
+  const sandbox = id === undefined ? null : await provider.resume({ id })
+  if (!sandbox) {
+    throw new Error(
+      'This thread has no computer. Take a screenshot, then call requestLogin again.',
+    )
+  }
+
+  // The password goes in the environment of one process, not on its command line.
+  const result = await sandbox.process.exec('python3 /opt/desktop/login.py', {
+    env: {
+      LOGIN_SITE: site,
+      LOGIN_USERNAME: login.username,
+      LOGIN_PASSWORD: login.password,
+    },
+  })
+  if (result.exitCode !== 0) {
+    throw new Error(`The sign-in failed: ${result.stderr.trim()}`)
+  }
+  const page = loginResultSchema.parse(JSON.parse(result.stdout))
+  return page.hasPasswordField
+    ? `The form was sent, but ${page.url} still shows a password field. The sign-in may have failed. Take a screenshot to check.`
+    : `Signed in. The browser shows ${page.url}. Take a screenshot to see it.`
+})
+```
+
+- `takeLogin` deletes the login, so the server uses each password once.
+- The tool result has no password. The model gets only the address of the page.
+
+Last, the harness and its HTTP handler:
+
+```typescript ignore
+const computer = computerUse({
+  driver: sandboxComputer({ provider, sandboxIds }),
+  screenshotDelay: 1000,
+})
+
+const agent = defineHarness({
+  name: 'computer-use-login',
+  adapter: openaiText('gpt-6.1-sol'),
+  systemPrompts: [
+    'You use a Linux desktop with Chromium on it. When a page asks you to sign in, call requestLogin with the address of the sign-in page. Never ask for a password in the chat, and never type one.',
+  ],
+  tools: [requestLogin],
+  plugins: () => [permissions(), computer],
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+export const handler = createHarnessHandler({
+  host,
+  harness: agent,
+  openAccess: true,
+})
+```
+
+- `sandboxComputer` makes one container for each thread. With `sandboxIds`, it keeps the container and reconnects to it later.
+- `memoryPersistence()` keeps the chat in memory. A server restart loses the chat, but not the container. For a user who comes back the next day, use a persistence store in your database. See [Chat persistence](../persistence/chat-persistence).
+- `openAccess` serves every request with no login. Use it only on your own machine. See [Serve with no login](../harness/access#serve-with-no-login).
+
+The Docker provider loads `dockerode`, which has native addons. Keep it out of the bundle in `vite.config.ts`:
+
+```typescript ignore
+export default defineConfig({
+  optimizeDeps: { exclude: ['dockerode'] },
+  ssr: { external: ['dockerode'] },
+  build: { rollupOptions: { external: ['dockerode'] } },
+  // ...your plugins
+})
+```
+
+## 5. Add the two routes
+
+Create `src/routes/api.harness.$.ts`. It serves the harness under `/api/harness`:
+
+```typescript ignore
+import { createFileRoute } from '@tanstack/react-router'
+import { handler } from '@/harness'
+
+export const Route = createFileRoute('/api/harness/$')({
+  server: {
+    handlers: {
+      GET: ({ request }) => handler(request),
+      POST: ({ request }) => handler(request),
+    },
+  },
+})
+```
+
+Create `src/routes/api.login.ts`. The card sends the login here. The route checks the input, keeps the login in memory, and logs nothing:
+
+```typescript ignore
+import { createFileRoute } from '@tanstack/react-router'
+import { loginSchema, saveLogin } from '@/harness'
+
+export const Route = createFileRoute('/api/login')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body: unknown = await request.json().catch(() => undefined)
+        const login = loginSchema.safeParse(body)
+        if (!login.success) {
+          return Response.json(
+            { error: 'Send a thread id, a site, a username, and a password.' },
+            { status: 400 },
+          )
+        }
+        saveLogin(login.data)
+        return new Response(null, { status: 204 })
+      },
+    },
+  },
+})
+```
+
+## 6. Show the login card
+
+In `src/routes/index.tsx`, give `useChat` the tool definition. The tool has no browser code, but `useChat` now types its approval:
+
+```tsx ignore
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { requestLoginTool } from '@/request-login'
+
+const THREAD_ID = 'computer-use-login'
+
+const { messages, sendMessage, interrupts } = useChat({
+  connection: fetchServerSentEvents('/api/harness/run'),
+  threadId: THREAD_ID,
+  tools: [requestLoginTool.client()],
+  // Load the thread from the server after a reload.
+  persistence: true,
+})
+```
+
+Add the card. It sends the login to `/api/login` first. Then it approves the tool call:
+
+```tsx ignore
+function LoginCard({
+  site,
+  onAnswer,
+}: {
+  site: string
+  onAnswer: (approved: boolean) => void
+}) {
+  const [username, setUsername] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState<string>()
+
+  const signIn = async (event: React.FormEvent) => {
+    event.preventDefault()
+    setError(undefined)
+    try {
+      const response = await fetch('/api/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ threadId: THREAD_ID, site, username, password }),
+      })
+      if (!response.ok) {
+        throw new Error(`The server did not take the login (${response.status}).`)
+      }
+      setPassword('')
+      onAnswer(true)
+    } catch (sendError) {
+      setError(sendError instanceof Error ? sendError.message : String(sendError))
+    }
+  }
+
+  return (
+    <form onSubmit={signIn}>
+      <p>Sign in to {new URL(site).origin}</p>
+      <input
+        value={username}
+        onChange={(event) => setUsername(event.target.value)}
+        autoComplete="username"
+        aria-label="Username"
+        required
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(event) => setPassword(event.target.value)}
+        autoComplete="current-password"
+        aria-label="Password"
+        required
+      />
+      {error ? <p>{error}</p> : null}
+      <button type="submit">Sign in</button>
+      <button type="button" onClick={() => onAnswer(false)}>
+        Cancel
+      </button>
+    </form>
+  )
+}
+```
+
+Show a card for each approval of `requestLogin`, below the messages:
+
+```tsx ignore
+{interrupts.map((interrupt) =>
+  interrupt.kind === 'tool-approval' ? (
+    <LoginCard
+      key={interrupt.id}
+      site={interrupt.originalArgs.site}
+      onAnswer={(approved) => interrupt.resolveInterrupt(approved)}
+    />
+  ) : null,
+)}
+```
+
+The harness keeps each screenshot in its media store. A tool result has a `harness-media:<id>` URL for it. Show it from the `media` path of the handler:
+
+```tsx ignore
+const src = `/api/harness/media?${new URLSearchParams({ threadId: THREAD_ID, id })}`
+```
+
+The example has the full page, with the screenshots and the card for OpenAI safety checks.
+
+## 7. Sign in
+
+Start the app with `npm run dev`. Send this task:
+
+```text
+Open https://the-internet.herokuapp.com/login in Chromium and sign in.
+When you are signed in, say what the page shows and stop.
+```
+
+The model opens the practice page and calls `requestLogin`. Type `tomsmith` and `SuperSecretPassword!` in the card, then click Sign in. The model says that the page shows the Secure Area. Your password is not in the chat, the tool result, or the harness log.
+
+The full example is on GitHub: [TanStack/ai `examples/react/computer-use-login`](https://github.com/TanStack/ai/tree/main/examples/react/computer-use-login). To host it, see [Run it on a server](https://github.com/TanStack/ai/tree/main/examples/react/computer-use-login#run-it-on-a-server) in its README.
diff --git a/docs/tutorials/computer-use.md b/docs/tutorials/computer-use.md
index 0d81a5041f..adfd184417 100644
--- a/docs/tutorials/computer-use.md
+++ b/docs/tutorials/computer-use.md
@@ -308,3 +308,5 @@ A Chromium window opens on tanstack.com. The model clicks through the site, and
 The full example is on GitHub: [TanStack/ai `examples/react/computer-use`](https://github.com/TanStack/ai/tree/main/examples/react/computer-use). It has the same task in the input box.
 
 To use Anthropic, change only the adapter. To run a full desktop in a sandbox, see [Drivers](../computer-use/drivers).
+
+To let the model sign in to a site without seeing the password, open [Sign In Without the Model](./computer-use-login).
diff --git a/examples/README.md b/examples/README.md
index 58ce2c069c..79e15f3106 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -15,6 +15,7 @@ Choose an example based on your use case:
 - **Want an agent in the terminal?** → [Harness CLI](#harness-cli)
 - **Want a signed MCP webhook?** → [MCP Events](#mcp-events)
 - **Want the model to use a web page?** → [Computer Use](#computer-use)
+- **Want the model to sign in without seeing the password?** → [Computer Use Login](#computer-use-login)
 - **Want a full-stack TypeScript app?** → [TanStack Chat (ts-react-chat)](#tanstack-chat-ts-react-chat)
 - **Need a live world stream?** → [World generation (ts-react-media)](#world-generation-ts-react-media)
 - **Need a vanilla JS frontend?** → [Vanilla Chat](#vanilla-chat)
@@ -204,6 +205,25 @@ Set `OPENAI_API_KEY` in `.env.local`. Open http://localhost:3100. Click Send.
 
 ---
 
+### Computer Use Login
+
+A TanStack Start app on the harness. The model uses a Docker desktop with Chromium. When a site asks for a password, a card in the chat asks you, and the server fills the form. The model never sees the password.
+
+**Path:** `examples/react/computer-use-login`
+
+**Getting Started:**
+
+```bash
+pnpm --filter computer-use-login build:desktop
+pnpm --filter computer-use-login dev
+```
+
+Start Docker first. Set `OPENAI_API_KEY` in `.env.local`. Open http://localhost:3100. Click Send.
+
+📖 [Full Documentation](react/computer-use-login/README.md)
+
+---
+
 ### TanStack Chat (ts-react-chat)
 
 A full-featured chat application built with the TanStack ecosystem.
diff --git a/examples/react/computer-use-login/.env.example b/examples/react/computer-use-login/.env.example
new file mode 100644
index 0000000000..00b69dfa39
--- /dev/null
+++ b/examples/react/computer-use-login/.env.example
@@ -0,0 +1,3 @@
+# The model reads the screenshots and picks each click. Get a key at
+# https://platform.openai.com/api-keys
+OPENAI_API_KEY=
diff --git a/examples/react/computer-use-login/.gitignore b/examples/react/computer-use-login/.gitignore
new file mode 100644
index 0000000000..74d4f47876
--- /dev/null
+++ b/examples/react/computer-use-login/.gitignore
@@ -0,0 +1,8 @@
+node_modules
+dist
+.env
+.env.local
+.nitro
+.tanstack
+.output
+.data
diff --git a/examples/react/computer-use-login/README.md b/examples/react/computer-use-login/README.md
new file mode 100644
index 0000000000..9c34e2b06d
--- /dev/null
+++ b/examples/react/computer-use-login/README.md
@@ -0,0 +1,62 @@
+# Computer Use Login
+
+Your agent uses a desktop, and a site asks it for a password. In this app, the model calls `requestLogin`. You type the username and password in a card in the chat. The server fills the form in the browser, and the model never sees the password.
+
+The desktop is a Docker container with Chromium on it. Each chat thread keeps its own container, so it stays signed in when you come back later.
+
+## Run it
+
+1. Start Docker.
+2. From the repo root, run `pnpm install`.
+3. Build the desktop image one time: `pnpm --filter computer-use-login build:desktop`.
+4. Copy `.env.example` to `.env.local`, then set `OPENAI_API_KEY`. Get a key at https://platform.openai.com/api-keys.
+5. Run `pnpm --filter computer-use-login dev`.
+6. Open http://localhost:3100 and click Send.
+
+The model opens a practice sign-in page. When the login card shows, type `tomsmith` and `SuperSecretPassword!`, then click Sign in. The model then says what the page shows.
+
+## How the password stays away from the model
+
+1. The model calls `requestLogin({ site })`. The tool has `needsApproval: true`, so the run stops, and the login card shows.
+2. The card sends the username and password to `/api/login`. That route keeps them in memory for 5 minutes, and logs nothing.
+3. The card then approves the tool call. The approval is only "yes". The harness writes approvals to its log, so a password must never be in one.
+4. The tool takes the login from memory and deletes it. It runs `sandbox/login.py` in the container, with the password in the environment of that one process, not on its command line.
+5. The script opens the site in Chromium and checks its origin. It fills the username and the password field, then submits the form. Then it clears every password field.
+6. The model gets "Signed in" and the address of the page.
+
+The model sees the screen, so Chromium must never show a password. `sandbox/policy.json` turns off the password manager and `javascript:` URLs. Chromium listens for its debugging protocol only inside the container. No port leaves it.
+
+## Files
+
+- `src/harness.ts`: the harness, the Docker provider, the `requestLogin` tool, and the two stores.
+- `src/request-login.ts`: the tool definition that the server and the browser share.
+- `src/routes/api.login.ts`: the route that takes the username and password.
+- `src/routes/index.tsx`: the chat and the login card.
+- `sandbox/`: the desktop image. `desktop.sh` starts the screen and Chromium. `login.py` fills the form.
+
+## Run it on a server
+
+The Docker setup runs on your own machine. To host the app, use a sandbox provider that pauses a sandbox and keeps its memory, like E2B:
+
+```ts
+import { e2bSandbox } from '@tanstack/ai-sandbox-e2b'
+
+const provider = e2bSandbox({
+  template: 'your-desktop-template',
+  onTimeout: 'pause',
+})
+```
+
+Build an E2B template from `sandbox/Dockerfile`, and start `desktop.sh` in it. Then move the two stores of `src/harness.ts` to your database: the sandbox id of each thread, and the logins (with a time limit).
+
+This app keeps the chat in `memoryPersistence()`. When the server restarts, the chat is gone, but the container stays. For a user who comes back the next day, give `createHarnessHost` a persistence store in your database. See [Chat persistence](https://tanstack.com/ai/latest/docs/persistence/chat-persistence).
+
+Cloudflare containers do not fit this app. Their disk is empty after each restart, so the browser signs out.
+
+## Not in this app
+
+- Two-factor codes.
+- A live view of the desktop for a captcha.
+- A saved Chromium profile in sandbox snapshots.
+
+CAUTION: The harness route has no login, and the browser can open every address that your server can reach. Run this app only on your own machine.
diff --git a/examples/react/computer-use-login/package.json b/examples/react/computer-use-login/package.json
new file mode 100644
index 0000000000..188c29a97a
--- /dev/null
+++ b/examples/react/computer-use-login/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "computer-use-login",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3100",
+    "build": "vite build",
+    "build:desktop": "docker build -t computer-use-login-desktop sandbox",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-computer-sandbox": "workspace:*",
+    "@tanstack/ai-computer-use": "workspace:*",
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-openai": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@tanstack/ai-react": "workspace:*",
+    "@tanstack/ai-sandbox-docker": "workspace:*",
+    "@tanstack/react-router": "^1.170.41",
+    "@tanstack/react-start": "^1.168.60",
+    "@tanstack/router-plugin": "^1.168.42",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tailwindcss": "^4.1.18",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "typescript": "5.9.3",
+    "vite": "^8.2.1"
+  }
+}
diff --git a/examples/react/computer-use-login/sandbox/Dockerfile b/examples/react/computer-use-login/sandbox/Dockerfile
new file mode 100644
index 0000000000..44ded1822d
--- /dev/null
+++ b/examples/react/computer-use-login/sandbox/Dockerfile
@@ -0,0 +1,18 @@
+# The desktop that the model uses: a screen, the tools of the sandbox
+# computer driver, Chromium, and the sign-in script.
+# Build it from the example folder: docker build -t computer-use-login-desktop sandbox
+FROM debian:bookworm-slim
+
+RUN printf 'Acquire::Retries "10";\nAcquire::ForceIPv4 "true";\n' > /etc/apt/apt.conf.d/80retries \
+  && apt-get update \
+  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    xvfb xdotool scrot x11-utils chromium fonts-dejavu-core \
+    python3 python3-websockets ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+# The model sees the screen and moves the mouse. So Chromium must never show
+# a password: no password manager, and no `javascript:` URLs.
+# (A DevTools policy would also close the debugging port that login.py uses.)
+COPY policy.json /etc/chromium/policies/managed/policy.json
+COPY desktop.sh login.py /opt/desktop/
+RUN chmod +x /opt/desktop/desktop.sh
diff --git a/examples/react/computer-use-login/sandbox/desktop.sh b/examples/react/computer-use-login/sandbox/desktop.sh
new file mode 100644
index 0000000000..2160d62e17
--- /dev/null
+++ b/examples/react/computer-use-login/sandbox/desktop.sh
@@ -0,0 +1,19 @@
+#!/bin/sh
+# The main process of the sandbox. It starts the screen and Chromium. When
+# Chromium closes, it starts again. The profile folder keeps the cookies, so a
+# restarted container is still signed in.
+# Chromium listens for the debugging protocol on 127.0.0.1 inside the
+# container only. The sign-in script uses it. No port leaves the container.
+rm -f /tmp/.X0-lock
+Xvfb :0 -ac -screen 0 1024x768x24 -nolisten tcp &
+until DISPLAY=:0 xdpyinfo >/dev/null 2>&1; do sleep 0.2; done
+
+while true; do
+  # --no-sandbox: Chromium runs as root in the container, which is the sandbox.
+  DISPLAY=:0 chromium --no-sandbox --test-type --no-first-run \
+    --no-default-browser-check --disable-dev-shm-usage \
+    --user-data-dir=/root/chromium-profile \
+    --remote-debugging-port=9222 \
+    --window-position=0,0 --window-size=1024,768 about:blank
+  sleep 1
+done
diff --git a/examples/react/computer-use-login/sandbox/login.py b/examples/react/computer-use-login/sandbox/login.py
new file mode 100644
index 0000000000..64b9701cbe
--- /dev/null
+++ b/examples/react/computer-use-login/sandbox/login.py
@@ -0,0 +1,143 @@
+"""Sign in on the site in the Chromium of this sandbox.
+
+The server runs this script with LOGIN_SITE, LOGIN_USERNAME, and
+LOGIN_PASSWORD in its environment, so the password is never on a command
+line. The script talks to Chromium over the debugging protocol on 127.0.0.1:
+
+1. Open LOGIN_SITE in the current tab.
+2. Stop if the page is not on the origin of LOGIN_SITE.
+3. Fill the username field and the password field, then submit the form.
+
+It prints one JSON line: the address of the page after the sign-in, and
+whether the page still has a password field. Errors go to stderr. No output
+has the password in it.
+"""
+
+import asyncio
+import json
+import os
+import sys
+import time
+import urllib.request
+from urllib.parse import urlsplit
+
+import websockets
+
+# Fills the last text field before the password field, then submits the form.
+# The native value setter and the input events make frameworks like React
+# see the values.
+FILL = """(username, password) => {
+  const visible = (input) => input.offsetParent !== null
+  const password_ = [...document.querySelectorAll('input[type=password]')].find(visible)
+  if (!password_) return 'The page has no visible password field.'
+  if (!password_.form) return 'The password field is not in a form.'
+  const inputs = [...password_.form.querySelectorAll('input')]
+  const user = inputs
+    .slice(0, inputs.indexOf(password_))
+    .reverse()
+    .find((input) => ['text', 'email', 'tel'].includes(input.type) && visible(input))
+  if (!user) return 'The form has no username field before the password field.'
+  const setValue = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set
+  for (const [input, value] of [[user, username], [password_, password]]) {
+    input.focus()
+    setValue.call(input, value)
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+    input.dispatchEvent(new Event('change', { bubbles: true }))
+  }
+  password_.form.requestSubmit()
+  return 'submitted'
+}"""
+
+TIMEOUT_S = 30
+
+
+class LoginError(Exception):
+    pass
+
+
+async def main():
+    site = os.environ["LOGIN_SITE"]
+    username = os.environ["LOGIN_USERNAME"]
+    password = os.environ["LOGIN_PASSWORD"]
+    parts = urlsplit(site)
+    origin = f"{parts.scheme}://{parts.netloc}"
+
+    with urllib.request.urlopen("http://127.0.0.1:9222/json/list") as response:
+        targets = json.load(response)
+    page = next((target for target in targets if target["type"] == "page"), None)
+    if page is None:
+        raise LoginError("Chromium has no open tab.")
+
+    async with websockets.connect(page["webSocketDebuggerUrl"], max_size=None) as socket:
+        next_id = 0
+
+        async def send(method, **params):
+            nonlocal next_id
+            next_id += 1
+            await socket.send(json.dumps({"id": next_id, "method": method, "params": params}))
+            while True:
+                message = json.loads(await socket.recv())
+                if message.get("id") == next_id:
+                    if "error" in message:
+                        raise LoginError(f"{method} failed: {message['error']['message']}")
+                    return message["result"]
+
+        async def evaluate(expression):
+            result = await send(
+                "Runtime.evaluate", expression=expression, returnByValue=True
+            )
+            # Never print the details: the expression can hold the password.
+            if "exceptionDetails" in result:
+                raise LoginError("A script on the page failed.")
+            return result["result"].get("value")
+
+        async def wait_for(condition):
+            deadline = time.monotonic() + TIMEOUT_S
+            while time.monotonic() < deadline:
+                try:
+                    if await evaluate(condition):
+                        return True
+                except LoginError:
+                    pass  # The page is loading. Try again.
+                await asyncio.sleep(0.2)
+            return False
+
+        await send("Page.navigate", url=site)
+        if not await wait_for("document.readyState === 'complete'"):
+            raise LoginError(f"{site} did not load in {TIMEOUT_S} s. Nothing was filled.")
+        # A redirect can leave the site. Then the form belongs to someone else.
+        page_origin = await evaluate("location.origin")
+        if page_origin != origin:
+            raise LoginError(f"The page is on {page_origin}, not {origin}. Nothing was filled.")
+
+        before = await evaluate("location.href")
+        result = await evaluate(f"({FILL})({json.dumps(username)}, {json.dumps(password)})")
+        if result != "submitted":
+            raise LoginError(result)
+
+        # A sign-in usually opens another page. A page that stays put is fine too.
+        await wait_for(
+            f"location.href !== {json.dumps(before)} && document.readyState === 'complete'"
+        )
+        # A sign-in that failed can leave the password in the field. Clear it,
+        # so nothing on the screen can show it.
+        await evaluate(
+            "document.querySelectorAll('input[type=password]').forEach((input) => { input.value = '' })"
+        )
+        print(
+            json.dumps(
+                {
+                    "url": await evaluate("location.href"),
+                    "hasPasswordField": await evaluate(
+                        "!!document.querySelector('input[type=password]')"
+                    ),
+                }
+            )
+        )
+
+
+try:
+    asyncio.run(main())
+except LoginError as error:
+    print(error, file=sys.stderr)
+    sys.exit(1)
diff --git a/examples/react/computer-use-login/sandbox/policy.json b/examples/react/computer-use-login/sandbox/policy.json
new file mode 100644
index 0000000000..05e27b20b0
--- /dev/null
+++ b/examples/react/computer-use-login/sandbox/policy.json
@@ -0,0 +1,6 @@
+{
+  "PasswordManagerEnabled": false,
+  "AutofillAddressEnabled": false,
+  "AutofillCreditCardEnabled": false,
+  "URLBlocklist": ["javascript://*"]
+}
diff --git a/examples/react/computer-use-login/src/harness.ts b/examples/react/computer-use-login/src/harness.ts
new file mode 100644
index 0000000000..330e481f6b
--- /dev/null
+++ b/examples/react/computer-use-login/src/harness.ts
@@ -0,0 +1,167 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { permissions } from '@tanstack/ai-harness/plugins'
+import { createHarnessHandler } from '@tanstack/ai-harness/server'
+import { computerUse } from '@tanstack/ai-computer-use/harness'
+import { sandboxComputer } from '@tanstack/ai-computer-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+import { openaiText } from '@tanstack/ai-openai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+import { requestLoginTool } from './request-login'
+
+// One Docker container for each chat thread. The image comes from
+// `sandbox/Dockerfile`. Its main process starts the screen and Chromium.
+const provider = dockerSandbox({
+  image: 'computer-use-login-desktop',
+  keepAliveCommand: ['/opt/desktop/desktop.sh'],
+})
+
+// The container id of each thread, in a file. A thread keeps its container,
+// and so its signed-in browser, also after the server restarts.
+// ponytail: one file and one process. Use your database with more servers.
+const SANDBOX_IDS_FILE = resolve('.data/sandbox-ids.json')
+const sandboxIdsSchema = z.record(z.string(), z.string())
+let sandboxIdsWrite: Promise<void> = Promise.resolve()
+
+async function readSandboxIds() {
+  try {
+    return sandboxIdsSchema.parse(
+      JSON.parse(await readFile(SANDBOX_IDS_FILE, 'utf8')),
+    )
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return {}
+    }
+    throw error
+  }
+}
+
+const sandboxIds = {
+  get: async (threadId: string) => (await readSandboxIds())[threadId],
+  set: (threadId: string, sandboxId: string) => {
+    // One write at a time, so two threads do not lose each other's id.
+    sandboxIdsWrite = sandboxIdsWrite.then(async () => {
+      const ids = await readSandboxIds()
+      await mkdir(dirname(SANDBOX_IDS_FILE), { recursive: true })
+      await writeFile(
+        SANDBOX_IDS_FILE,
+        JSON.stringify({ ...ids, [threadId]: sandboxId }),
+      )
+    })
+    return sandboxIdsWrite
+  },
+}
+
+// The username and password of each thread, between the login card and the
+// sign-in. Only in memory, and never in a log.
+// ponytail: one process. With more servers, use a store with a time limit.
+const LOGIN_TTL_MS = 5 * 60_000
+const logins = new Map<
+  string,
+  {
+    site: string
+    username: string
+    password: string
+    timer: ReturnType<typeof setTimeout>
+  }
+>()
+
+export const loginSchema = z.object({
+  threadId: z.string().min(1).max(200),
+  site: z.url({ protocol: /^https?$/ }).max(2000),
+  username: z.string().min(1).max(500),
+  password: z.string().min(1).max(500),
+})
+
+/** Keep a username and password for the next sign-in of a thread. */
+export function saveLogin({ threadId, ...login }: z.infer<typeof loginSchema>) {
+  clearTimeout(logins.get(threadId)?.timer)
+  const timer = setTimeout(() => logins.delete(threadId), LOGIN_TTL_MS)
+  timer.unref()
+  logins.set(threadId, { ...login, timer })
+}
+
+/** Take the saved login of a thread. It is deleted, so it is used once. */
+function takeLogin(threadId: string, site: string) {
+  const login = logins.get(threadId)
+  logins.delete(threadId)
+  clearTimeout(login?.timer)
+  if (!login) {
+    throw new Error(
+      'The user gave no username and password. Call requestLogin again.',
+    )
+  }
+  if (new URL(login.site).origin !== new URL(site).origin) {
+    throw new Error(
+      `The user signed in for ${new URL(login.site).origin}, not ${new URL(site).origin}.`,
+    )
+  }
+  return login
+}
+
+const loginResultSchema = z.object({
+  url: z.string(),
+  hasPasswordField: z.boolean(),
+})
+
+// The model asks for a sign-in, and it never sees the password.
+const requestLogin = requestLoginTool.server(async ({ site }, context) => {
+  const threadId = context?.threadId
+  if (!threadId) throw new Error('requestLogin runs only in a chat thread.')
+  const login = takeLogin(threadId, site)
+
+  // The user can answer the card hours later. The container of the thread
+  // can be stopped by then. `resume` starts it again.
+  const id = await sandboxIds.get(threadId)
+  const sandbox = id === undefined ? null : await provider.resume({ id })
+  if (!sandbox) {
+    throw new Error(
+      'This thread has no computer. Take a screenshot, then call requestLogin again.',
+    )
+  }
+
+  // The password goes in the environment of one process, not on its command
+  // line. The script opens the site, checks its origin, then fills the form.
+  const result = await sandbox.process.exec('python3 /opt/desktop/login.py', {
+    env: {
+      LOGIN_SITE: site,
+      LOGIN_USERNAME: login.username,
+      LOGIN_PASSWORD: login.password,
+    },
+  })
+  if (result.exitCode !== 0) {
+    throw new Error(`The sign-in failed: ${result.stderr.trim()}`)
+  }
+  const page = loginResultSchema.parse(JSON.parse(result.stdout))
+  return page.hasPasswordField
+    ? `The form was sent, but ${page.url} still shows a password field. The sign-in may have failed. Take a screenshot to check.`
+    : `Signed in. The browser shows ${page.url}. Take a screenshot to see it.`
+})
+
+// One time, outside `plugins`, so every session shares the containers.
+const computer = computerUse({
+  driver: sandboxComputer({ provider, sandboxIds }),
+  // Pages load in a real browser. Give each one time to draw.
+  screenshotDelay: 1000,
+})
+
+const agent = defineHarness({
+  name: 'computer-use-login',
+  adapter: openaiText('gpt-6.1-sol'),
+  systemPrompts: [
+    'You use a Linux desktop with Chromium on it. When a page asks you to sign in, call requestLogin with the address of the sign-in page. Never ask for a password in the chat, and never type one.',
+  ],
+  tools: [requestLogin],
+  plugins: () => [permissions(), computer],
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+// No login: run this app only on your own machine.
+export const handler = createHarnessHandler({
+  host,
+  harness: agent,
+  openAccess: true,
+})
diff --git a/examples/react/computer-use-login/src/request-login.ts b/examples/react/computer-use-login/src/request-login.ts
new file mode 100644
index 0000000000..8ed6ba9c8a
--- /dev/null
+++ b/examples/react/computer-use-login/src/request-login.ts
@@ -0,0 +1,20 @@
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+// The server and the browser both import this definition. The server gives
+// it the code (`src/harness.ts`). The browser gets the typed approval card.
+export const requestLoginTool = toolDefinition({
+  name: 'requestLogin',
+  description:
+    'Ask the user to sign in to a site. The user types the username and password in a form that you never see, and the server fills the sign-in form in the browser. Call it when a page asks for a password. Pass the address of the sign-in page.',
+  // The run stops until the user answers the login card. The answer is only
+  // "yes", so the harness log and the persistence keep no secret.
+  needsApproval: true,
+  inputSchema: z.object({
+    site: z
+      .url({ protocol: /^https?$/ })
+      .describe(
+        'The address of the sign-in page, for example https://example.com/login',
+      ),
+  }),
+})
diff --git a/examples/react/computer-use-login/src/routeTree.gen.ts b/examples/react/computer-use-login/src/routeTree.gen.ts
new file mode 100644
index 0000000000..f093a916e8
--- /dev/null
+++ b/examples/react/computer-use-login/src/routeTree.gen.ts
@@ -0,0 +1,104 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as ApiLoginRouteImport } from './routes/api.login'
+import { Route as ApiHarnessSplatRouteImport } from './routes/api.harness.$'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiLoginRoute = ApiLoginRouteImport.update({
+  id: '/api/login',
+  path: '/api/login',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiHarnessSplatRoute = ApiHarnessSplatRouteImport.update({
+  id: '/api/harness/$',
+  path: '/api/harness/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/api/login': typeof ApiLoginRoute
+  '/api/harness/$': typeof ApiHarnessSplatRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/api/login': typeof ApiLoginRoute
+  '/api/harness/$': typeof ApiHarnessSplatRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/api/login': typeof ApiLoginRoute
+  '/api/harness/$': typeof ApiHarnessSplatRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/api/login' | '/api/harness/$'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/api/login' | '/api/harness/$'
+  id: '__root__' | '/' | '/api/login' | '/api/harness/$'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ApiLoginRoute: typeof ApiLoginRoute
+  ApiHarnessSplatRoute: typeof ApiHarnessSplatRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/login': {
+      id: '/api/login'
+      path: '/api/login'
+      fullPath: '/api/login'
+      preLoaderRoute: typeof ApiLoginRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/harness/$': {
+      id: '/api/harness/$'
+      path: '/api/harness/$'
+      fullPath: '/api/harness/$'
+      preLoaderRoute: typeof ApiHarnessSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ApiLoginRoute: ApiLoginRoute,
+  ApiHarnessSplatRoute: ApiHarnessSplatRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}
diff --git a/examples/react/computer-use-login/src/router.tsx b/examples/react/computer-use-login/src/router.tsx
new file mode 100644
index 0000000000..a595444648
--- /dev/null
+++ b/examples/react/computer-use-login/src/router.tsx
@@ -0,0 +1,10 @@
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export const getRouter = () => {
+  return createRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreloadStaleTime: 0,
+  })
+}
diff --git a/examples/react/computer-use-login/src/routes/__root.tsx b/examples/react/computer-use-login/src/routes/__root.tsx
new file mode 100644
index 0000000000..4fc02422d9
--- /dev/null
+++ b/examples/react/computer-use-login/src/routes/__root.tsx
@@ -0,0 +1,41 @@
+import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
+import appCss from '../styles.css?url'
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      {
+        charSet: 'utf-8',
+      },
+      {
+        name: 'viewport',
+        content: 'width=device-width, initial-scale=1',
+      },
+      {
+        title: 'Computer Use Login',
+      },
+    ],
+    links: [
+      {
+        rel: 'stylesheet',
+        href: appCss,
+      },
+    ],
+  }),
+
+  shellComponent: RootDocument,
+})
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body className="min-h-screen bg-gray-900">
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
diff --git a/examples/react/computer-use-login/src/routes/api.harness.$.ts b/examples/react/computer-use-login/src/routes/api.harness.$.ts
new file mode 100644
index 0000000000..9072efb42f
--- /dev/null
+++ b/examples/react/computer-use-login/src/routes/api.harness.$.ts
@@ -0,0 +1,12 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { handler } from '@/harness'
+
+// The harness answers every path under /api/harness, like /api/harness/run.
+export const Route = createFileRoute('/api/harness/$')({
+  server: {
+    handlers: {
+      GET: ({ request }) => handler(request),
+      POST: ({ request }) => handler(request),
+    },
+  },
+})
diff --git a/examples/react/computer-use-login/src/routes/api.login.ts b/examples/react/computer-use-login/src/routes/api.login.ts
new file mode 100644
index 0000000000..98e1841b87
--- /dev/null
+++ b/examples/react/computer-use-login/src/routes/api.login.ts
@@ -0,0 +1,25 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { loginSchema, saveLogin } from '@/harness'
+
+// The login card sends the username and password here, not to the harness.
+// The harness logs every answer. This route keeps the login in memory until
+// the requestLogin tool uses it, and logs nothing.
+export const Route = createFileRoute('/api/login')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        // A body that is not JSON fails the check below too.
+        const body: unknown = await request.json().catch(() => undefined)
+        const login = loginSchema.safeParse(body)
+        if (!login.success) {
+          return Response.json(
+            { error: 'Send a thread id, a site, a username, and a password.' },
+            { status: 400 },
+          )
+        }
+        saveLogin(login.data)
+        return new Response(null, { status: 204 })
+      },
+    },
+  },
+})
diff --git a/examples/react/computer-use-login/src/routes/index.tsx b/examples/react/computer-use-login/src/routes/index.tsx
new file mode 100644
index 0000000000..9d443a52f2
--- /dev/null
+++ b/examples/react/computer-use-login/src/routes/index.tsx
@@ -0,0 +1,316 @@
+import { useEffect, useRef, useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { requestLoginTool } from '@/request-login'
+import type { UIMessage } from '@tanstack/ai-react'
+
+const THREAD_ID = 'computer-use-login'
+
+const TASK = `Open https://the-internet.herokuapp.com/login in Chromium and sign in.
+When you are signed in, say what the page shows and stop.`
+
+type Part = UIMessage['parts'][number]
+
+const MEDIA_PREFIX = 'harness-media:'
+
+/**
+ * The screenshots in one tool result, as `<img>` sources. The harness keeps
+ * each screenshot in its media store. The message has only its id.
+ */
+function screenshots(part: Part) {
+  if (part.type !== 'tool-result' || typeof part.content === 'string') return []
+  return part.content.flatMap((content) => {
+    if (content.type !== 'image') return []
+    const { source } = content
+    if (source.type === 'data') {
+      return [`data:${source.mimeType};base64,${source.value}`]
+    }
+    if (source.value.startsWith(MEDIA_PREFIX)) {
+      const id = source.value.slice(MEDIA_PREFIX.length)
+      return [
+        `/api/harness/media?${new URLSearchParams({ threadId: THREAD_ID, id })}`,
+      ]
+    }
+    return [source.value]
+  })
+}
+
+function Messages({ messages }: { messages: ReadonlyArray<UIMessage> }) {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (containerRef.current) {
+      containerRef.current.scrollTop = containerRef.current.scrollHeight
+    }
+  }, [messages])
+
+  if (!messages.length) {
+    return (
+      <div className="flex-1 overflow-y-auto px-4 py-8">
+        <div className="mx-auto max-w-2xl text-center">
+          <h2 className="mb-2 text-xl font-semibold text-white">
+            Sign in without the model
+          </h2>
+          <p className="text-sm text-gray-400">
+            Click Send. The model opens a sign-in page in a Docker desktop. When
+            it needs a password, a card asks you. The model never sees what you
+            type.
+          </p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div ref={containerRef} className="flex-1 overflow-y-auto px-4 py-4">
+      {messages.map((message) => (
+        <div
+          key={message.id}
+          className={`mb-2 rounded-lg p-4 ${
+            message.role === 'assistant'
+              ? 'bg-linear-to-r from-orange-500/5 to-red-600/5'
+              : 'bg-transparent'
+          }`}
+        >
+          {message.parts.map((part, index) => {
+            if (part.type === 'text' && part.content) {
+              return (
+                <div key={index} className="whitespace-pre-wrap text-white">
+                  {part.content}
+                </div>
+              )
+            }
+            return screenshots(part).map((src) => (
+              <img
+                key={`${index}-${src.slice(-16)}`}
+                src={src}
+                alt="What the model sees"
+                className="my-2 max-w-xl rounded border border-gray-700"
+              />
+            ))
+          })}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/**
+ * The model asked for a sign-in. The username and password go to
+ * `/api/login`, not to the chat. The answer to the model is only "yes".
+ */
+function LoginCard({
+  site,
+  onAnswer,
+}: {
+  site: string
+  onAnswer: (approved: boolean) => void
+}) {
+  const [username, setUsername] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState<string>()
+  const [isSending, setIsSending] = useState(false)
+
+  const signIn = async (event: React.FormEvent) => {
+    event.preventDefault()
+    setIsSending(true)
+    setError(undefined)
+    try {
+      const response = await fetch('/api/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ threadId: THREAD_ID, site, username, password }),
+      })
+      if (!response.ok) {
+        throw new Error(
+          `The server did not take the login (${response.status}).`,
+        )
+      }
+      setPassword('')
+      onAnswer(true)
+    } catch (sendError) {
+      setError(
+        sendError instanceof Error ? sendError.message : String(sendError),
+      )
+      setIsSending(false)
+    }
+  }
+
+  return (
+    <form
+      onSubmit={signIn}
+      className="mx-4 mt-2 flex flex-col gap-2 rounded-lg border border-orange-500/30 bg-orange-500/10 p-3 text-sm text-orange-100"
+    >
+      <p className="font-medium">
+        Sign in to <span className="font-mono">{new URL(site).origin}</span>
+      </p>
+      <p className="text-xs text-orange-200/80">
+        The server fills the form in the browser. The model never sees your
+        password.
+      </p>
+      <input
+        value={username}
+        onChange={(event) => setUsername(event.target.value)}
+        autoComplete="username"
+        placeholder="Username"
+        aria-label="Username"
+        required
+        className="rounded border border-gray-700 bg-gray-800 px-3 py-2 text-white"
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(event) => setPassword(event.target.value)}
+        autoComplete="current-password"
+        placeholder="Password"
+        aria-label="Password"
+        required
+        className="rounded border border-gray-700 bg-gray-800 px-3 py-2 text-white"
+      />
+      {error ? <p className="text-red-400">{error}</p> : null}
+      <div className="flex gap-2">
+        <button
+          type="submit"
+          disabled={isSending}
+          className="rounded bg-orange-500 px-3 py-1 text-white disabled:opacity-50"
+        >
+          {isSending ? 'Signing in…' : 'Sign in'}
+        </button>
+        <button
+          type="button"
+          disabled={isSending}
+          onClick={() => onAnswer(false)}
+          className="rounded bg-gray-700 px-3 py-1 text-white"
+        >
+          Cancel
+        </button>
+      </div>
+    </form>
+  )
+}
+
+/** Another approval, like an OpenAI safety check on a computer action. */
+function ApprovalCard({
+  message,
+  onAnswer,
+}: {
+  message: string | undefined
+  onAnswer: (approved: boolean) => void
+}) {
+  return (
+    <div className="mx-4 mt-2 rounded-lg border border-yellow-500/30 bg-yellow-500/10 p-3 text-sm text-yellow-100">
+      <p className="mb-2 font-medium">{message ?? 'Approve this action?'}</p>
+      <div className="flex gap-2">
+        <button
+          type="button"
+          onClick={() => onAnswer(true)}
+          className="rounded bg-orange-500 px-3 py-1 text-white"
+        >
+          Approve
+        </button>
+        <button
+          type="button"
+          onClick={() => onAnswer(false)}
+          className="rounded bg-gray-700 px-3 py-1 text-white"
+        >
+          Decline
+        </button>
+      </div>
+    </div>
+  )
+}
+
+function ChatPage() {
+  const [input, setInput] = useState(TASK)
+  const { messages, sendMessage, isLoading, error, stop, interrupts } = useChat(
+    {
+      connection: fetchServerSentEvents('/api/harness/run'),
+      threadId: THREAD_ID,
+      // No browser code: the tool runs on the server. This gives the
+      // approval of the tool its typed arguments.
+      tools: [requestLoginTool.client()],
+      // Load the thread from the server after a reload.
+      persistence: true,
+    },
+  )
+
+  const handleSendMessage = () => {
+    if (!input.trim()) return
+    sendMessage(input.trim())
+    setInput('')
+  }
+
+  return (
+    <div className="flex h-screen bg-gray-900">
+      <div className="flex w-full flex-col">
+        <Messages messages={messages} />
+
+        {interrupts.map((interrupt) => {
+          if (interrupt.kind === 'tool-approval') {
+            return (
+              <LoginCard
+                key={interrupt.id}
+                site={interrupt.originalArgs.site}
+                onAnswer={(approved) => interrupt.resolveInterrupt(approved)}
+              />
+            )
+          }
+          if (interrupt.kind === 'generic') {
+            return (
+              <ApprovalCard
+                key={interrupt.id}
+                message={interrupt.message}
+                onAnswer={(approved) => interrupt.resolveInterrupt(approved)}
+              />
+            )
+          }
+          return null
+        })}
+
+        {error ? (
+          <div className="mx-4 mt-2 rounded-lg border border-red-500/30 bg-red-500/10 p-3 text-sm text-red-400">
+            {error.message}
+          </div>
+        ) : null}
+
+        <div className="border-t border-orange-500/10 bg-gray-900/80">
+          <div className="w-full px-4 py-3">
+            {isLoading ? (
+              <div className="mb-3 flex items-center justify-center">
+                <button
+                  type="button"
+                  onClick={stop}
+                  className="rounded-lg bg-red-600 px-4 py-2 text-sm font-medium text-white hover:bg-red-700"
+                >
+                  Stop
+                </button>
+              </div>
+            ) : null}
+            <div className="flex items-end gap-2">
+              <textarea
+                value={input}
+                onChange={(event) => setInput(event.target.value)}
+                placeholder="Tell the model what to do on the desktop..."
+                className="w-full resize-none rounded-lg border border-orange-500/20 bg-gray-800/50 px-4 py-3 text-sm text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-orange-500/50"
+                rows={3}
+                disabled={isLoading}
+              />
+              <button
+                type="button"
+                onClick={handleSendMessage}
+                disabled={!input.trim() || isLoading}
+                className="rounded-lg bg-orange-500 px-4 py-3 text-sm font-medium text-white disabled:opacity-50"
+              >
+                Send
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export const Route = createFileRoute('/')({
+  component: ChatPage,
+})
diff --git a/examples/react/computer-use-login/src/styles.css b/examples/react/computer-use-login/src/styles.css
new file mode 100644
index 0000000000..2cd2c65a05
--- /dev/null
+++ b/examples/react/computer-use-login/src/styles.css
@@ -0,0 +1,10 @@
+@import 'tailwindcss';
+
+body {
+  @apply m-0;
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu',
+    'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
diff --git a/examples/react/computer-use-login/tsconfig.json b/examples/react/computer-use-login/tsconfig.json
new file mode 100644
index 0000000000..3fd120cf69
--- /dev/null
+++ b/examples/react/computer-use-login/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "target": "ES2022",
+    "allowJs": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowImportingTsExtensions": true,
+    "types": ["vite/client", "node"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
diff --git a/examples/react/computer-use-login/vite.config.ts b/examples/react/computer-use-login/vite.config.ts
new file mode 100644
index 0000000000..f9385950f7
--- /dev/null
+++ b/examples/react/computer-use-login/vite.config.ts
@@ -0,0 +1,26 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+// Server routes read process.env. Vite does not copy unprefixed .env keys
+// into the SSR process. Load them here. Already-set vars win.
+for (const name of ['.env.local', '.env']) {
+  const path = resolve(import.meta.dirname, name)
+  if (existsSync(path)) process.loadEnvFile(path)
+}
+
+// The Docker provider uses `dockerode`. It loads native addons that the
+// bundler cannot inline, so the server loads it from node_modules.
+const SERVER_ONLY = ['dockerode']
+
+export default defineConfig({
+  resolve: { tsconfigPaths: true },
+  optimizeDeps: { exclude: SERVER_ONLY },
+  ssr: { external: SERVER_ONLY },
+  build: { rollupOptions: { external: SERVER_ONLY } },
+  server: { port: 3100 },
+  plugins: [tailwindcss(), tanstackStart(), viteReact()],
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5ef6b0003b..bc6a0042e8 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -327,6 +327,76 @@ importers:
         specifier: ^8.2.1
         version: 8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
 
+  examples/react/computer-use-login:
+    dependencies:
+      '@tailwindcss/vite':
+        specifier: ^4.1.18
+        version: 4.1.18(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../../../packages/ai
+      '@tanstack/ai-computer-sandbox':
+        specifier: workspace:*
+        version: link:../../../packages/ai-computer-sandbox
+      '@tanstack/ai-computer-use':
+        specifier: workspace:*
+        version: link:../../../packages/ai-computer-use
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../../../packages/ai-harness
+      '@tanstack/ai-openai':
+        specifier: workspace:*
+        version: link:../../../packages/ai-openai
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../../../packages/ai-persistence
+      '@tanstack/ai-react':
+        specifier: workspace:*
+        version: link:../../../packages/ai-react
+      '@tanstack/ai-sandbox-docker':
+        specifier: workspace:*
+        version: link:../../../packages/ai-sandbox-docker
+      '@tanstack/react-router':
+        specifier: ^1.170.41
+        version: 1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@tanstack/react-start':
+        specifier: ^1.168.60
+        version: 1.168.60(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.1)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/router-plugin':
+        specifier: ^1.168.42
+        version: 1.168.42(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(esbuild@0.28.1)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      react:
+        specifier: ^19.2.3
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.2.3
+        version: 19.2.3(react@19.2.3)
+      tailwindcss:
+        specifier: ^4.1.18
+        version: 4.1.18
+      zod:
+        specifier: ^4.2.0
+        version: 4.6.5
+    devDependencies:
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.13.6
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.3.0
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.3.0)
+      '@vitejs/plugin-react':
+        specifier: ^5.2.0
+        version: 5.2.0(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      typescript:
+        specifier: 5.9.3
+        version: 5.9.3
+      vite:
+        specifier: ^8.2.1
+        version: 8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+
   examples/react/evaluate:
     dependencies:
       '@tailwindcss/vite':

From a23850b07b71c5cb0b3113294bd0c5d80ad4fc68 Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Tue, 3 Nov 2026 17:47:33 +0700
Subject: [PATCH 4/7] feat(ai-computer-sandbox): save a thread's files with
 snapshots and restore them into a new sandbox

---
 .changeset/computer-sandbox-snapshots.md      |   8 ++
 docs/computer-use/drivers.md                  |  50 ++++++-
 packages/ai-computer-sandbox/README.md        |  22 +++
 packages/ai-computer-sandbox/src/driver.ts    | 123 ++++++++++++++++-
 packages/ai-computer-sandbox/src/index.ts     |   2 +
 .../ai-computer-sandbox/tests/driver.test.ts  | 129 +++++++++++++++++-
 packages/ai-sandbox/src/index.ts              |   7 +-
 7 files changed, 333 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/computer-sandbox-snapshots.md

diff --git a/.changeset/computer-sandbox-snapshots.md b/.changeset/computer-sandbox-snapshots.md
new file mode 100644
index 0000000000..5cf128ad72
--- /dev/null
+++ b/.changeset/computer-sandbox-snapshots.md
@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-computer-sandbox': minor
+'@tanstack/ai-sandbox': minor
+---
+
+`sandboxComputer()` takes a `snapshots` option. The driver saves the files of one folder, like a browser profile, when a thread closes or goes idle. It restores them into the next new sandbox of the thread, so a sign-in survives a sandbox that is gone. This works with every provider. Call `saveComputerSnapshot()` to save right away, for example after a sign-in.
+
+`@tanstack/ai-sandbox` exports `captureSandboxFiles` and `restoreSandboxFiles`, the file capture and restore of portable snapshots.
diff --git a/docs/computer-use/drivers.md b/docs/computer-use/drivers.md
index 7f4ee94679..01a3044f4f 100644
--- a/docs/computer-use/drivers.md
+++ b/docs/computer-use/drivers.md
@@ -131,11 +131,12 @@ const computerUse = createComputerUse({
 - `provider`: the sandbox provider. It makes one sandbox for each thread.
 - `display`: the screen size of each desktop in pixels. The default is 1024 x 768.
 - `sandboxIds`: keep the desktop of each thread and reconnect to it later. See [Keep the desktop for later](#keep-the-desktop-for-later).
+- `snapshots`: save the files of a folder, and restore them into the next new sandbox of the thread. See [Restore files into a new sandbox](#restore-files-into-a-new-sandbox).
 
 How the sandbox driver behaves:
 
 - There is no `navigate` tool, because a desktop has no address. The model opens the browser on the desktop.
-- When a thread closes or goes idle, `createComputerUse` destroys its sandbox, unless you set `sandboxIds`.
+- When a thread closes or goes idle, `createComputerUse` destroys its sandbox, unless you set `sandboxIds`. With `snapshots`, the driver saves the files first.
 - One scroll step is 100 pixels.
 - The driver quotes every key name and all typed text before they go to the shell.
 
@@ -203,6 +204,53 @@ What each provider keeps:
 > [!WARNING]
 > A kept desktop holds what the user did in it, like signed-in browser sessions. Delete the sandbox when the user deletes the thread.
 
+### Restore files into a new sandbox
+
+Give `sandboxComputer()` a `snapshots` option. The driver saves the files of one folder, like the browser profile. When the sandbox of a thread is gone, the next new sandbox gets those files, so the browser is still signed in. This works with every provider, also when its disk does not last, like Cloudflare.
+
+```ts
+import { createComputerUse } from '@tanstack/ai-computer-use'
+import { sandboxComputer } from '@tanstack/ai-computer-sandbox'
+import { memorySandboxSnapshots } from '@tanstack/ai-sandbox'
+import { e2bSandbox } from '@tanstack/ai-sandbox-e2b'
+import type { SandboxHandle } from '@tanstack/ai-sandbox'
+
+async function run(sandbox: SandboxHandle, command: string) {
+  const result = await sandbox.process.exec(command)
+  if (result.exitCode !== 0) throw new Error(result.stderr)
+}
+
+const computerUse = createComputerUse({
+  driver: sandboxComputer({
+    provider: e2bSandbox({ template: 'my-desktop' }),
+    snapshots: {
+      store: await memorySandboxSnapshots(),
+      root: '/home/user/browser-profile',
+      // Skip the caches. They are large, and the browser makes them again.
+      policy: { exclude: (path) => path.includes('Cache') },
+      // The browser writes its profile all the time. Close it cleanly during
+      // a save. A kill signal can stop it before it writes its cookies.
+      before: (sandbox) => run(sandbox, 'stop-browser'),
+      after: (sandbox) => run(sandbox, 'start-browser'),
+    },
+  }),
+})
+```
+
+With `snapshots`, the driver works like this:
+
+- When a thread closes or goes idle, the driver runs `before`, saves the files under `root`, then runs `after`.
+- When the driver creates a new sandbox for a thread with a saved snapshot, it runs `before`, restores the files, then runs `after`.
+- A sandbox that the driver reconnects to with `sandboxIds` keeps its own files. The driver restores nothing into it.
+- Each save becomes the newest checkpoint of the thread. Use these stores only for computers.
+
+To save at a moment that you must keep, like right after a sign-in, call `saveComputerSnapshot(sandbox, threadId, snapshots)` with the same options. The [sign-in tutorial](../tutorials/computer-use-login) does this.
+
+`memorySandboxSnapshots()` keeps the files in memory, so they are lost when the server stops. For a user who comes back the next day, build the stores with `createSandboxSnapshots` on your database.
+
+> [!WARNING]
+> A snapshot of a browser profile holds its session cookies. A person with the cookies can use the signed-in accounts. Keep the blob store secret, and encrypt it in production.
+
 Do you already have a desktop sandbox? See [Share one sandbox](#share-one-sandbox).
 
 ## Your own computer
diff --git a/packages/ai-computer-sandbox/README.md b/packages/ai-computer-sandbox/README.md
index 0550f18baa..dab1d185a4 100644
--- a/packages/ai-computer-sandbox/README.md
+++ b/packages/ai-computer-sandbox/README.md
@@ -85,6 +85,28 @@ const computerUse = createComputerUse({
 - A later call of the thread reconnects with `provider.resume`. If the sandbox is gone, the driver creates a new one and stores its id.
 - The driver never destroys a kept sandbox. The provider timeout pauses or removes it.
 
+## Restore files into a new sandbox
+
+Give `sandboxComputer()` a `snapshots` option. The driver saves the files of one folder, like the browser profile, when a thread closes or goes idle. The next new sandbox of the thread gets those files back. This works with every provider.
+
+```typescript
+const computerUse = createComputerUse({
+  driver: sandboxComputer({
+    provider,
+    snapshots: {
+      store: await memorySandboxSnapshots(),
+      root: '/home/user/browser-profile',
+      before: (sandbox) => stopBrowser(sandbox),
+      after: (sandbox) => startBrowser(sandbox),
+    },
+  }),
+})
+```
+
+- `before` runs before each save and restore. Stop the programs that write in `root`. `after` starts them again.
+- To save right away, like after a sign-in, call `saveComputerSnapshot(sandbox, threadId, snapshots)`.
+- A snapshot of a browser profile holds its session cookies. Keep the store secret.
+
 ## Share one sandbox
 
 To drive a sandbox that you already have, use `createSandboxComputerDriver`. Every thread shares this sandbox, so it serves one conversation at a time.
diff --git a/packages/ai-computer-sandbox/src/driver.ts b/packages/ai-computer-sandbox/src/driver.ts
index aa7cfe71ca..43a3dacca5 100644
--- a/packages/ai-computer-sandbox/src/driver.ts
+++ b/packages/ai-computer-sandbox/src/driver.ts
@@ -4,7 +4,13 @@ import type {
   ComputerDriverFactory,
   MouseButton,
 } from '@tanstack/ai-computer-use'
-import type { SandboxHandle, SandboxProvider } from '@tanstack/ai-sandbox'
+import { captureSandboxFiles, restoreSandboxFiles } from '@tanstack/ai-sandbox'
+import type {
+  SandboxHandle,
+  SandboxProvider,
+  SandboxSnapshotPolicy,
+  SandboxSnapshots,
+} from '@tanstack/ai-sandbox'
 
 /** Options for {@link createSandboxComputerDriver}. */
 export interface SandboxComputerDriverOptions {
@@ -34,6 +40,30 @@ export interface SandboxComputerOptions {
     get: (threadId: string) => Promise<string | undefined>
     set: (threadId: string, sandboxId: string) => Promise<void>
   }
+  /**
+   * Save the files of a folder when a thread closes or goes idle, and restore
+   * them into the next new sandbox of the thread. This works with every
+   * provider, also when the sandbox is gone.
+   */
+  snapshots?: SandboxComputerSnapshots
+}
+
+/** Options for the saved files of each thread. See {@link saveComputerSnapshot}. */
+export interface SandboxComputerSnapshots {
+  /**
+   * The stores from `createSandboxSnapshots` or `memorySandboxSnapshots`.
+   * Each save becomes the newest checkpoint of the thread, so use these
+   * stores only for computers.
+   */
+  store: Pick<SandboxSnapshots, 'persistence' | 'checkpoints'>
+  /** The folder to save, as an absolute path. */
+  root: string
+  /** The paths to skip. The default skips `.git`, `node_modules`, and `.env` files. */
+  policy?: SandboxSnapshotPolicy
+  /** Runs before each save and restore. Stop the programs that write in `root`. */
+  before?: (sandbox: SandboxHandle) => Promise<void>
+  /** Runs after each save and restore. Start those programs again. */
+  after?: (sandbox: SandboxHandle) => Promise<void>
 }
 
 const DEFAULT_DISPLAY = { width: 1024, height: 768 }
@@ -245,7 +275,9 @@ export async function createSandboxComputerDriver({
  * Each sandbox comes from `provider.create`. When `createComputerUse` closes
  * a thread, or the thread goes idle, the sandbox of that thread is
  * destroyed. With `sandboxIds`, the sandbox is kept, and the next call of the
- * thread reconnects to it with `provider.resume`. The drivers have `cursorPosition`. They have no `zoom` and no
+ * thread reconnects to it with `provider.resume`. With `snapshots`, the files
+ * of one folder are saved first, and restored into the next new sandbox of
+ * the thread. The drivers have `cursorPosition`. They have no `zoom` and no
  * `navigate`, because a desktop has no address. The model opens the browser
  * on the desktop.
  *
@@ -260,6 +292,7 @@ export function sandboxComputer({
   provider,
   display = DEFAULT_DISPLAY,
   sandboxIds,
+  snapshots,
 }: SandboxComputerOptions) {
   /** The sandbox of the thread: its stored sandbox, when it still exists, or a new one. */
   async function open(threadId: string) {
@@ -290,9 +323,23 @@ export function sandboxComputer({
             `The sandbox display is ${width}x${height}, not ${display.width}x${display.height}. Set display to the size of the running display.`,
           )
         }
+        if (isNew && snapshots) {
+          await restoreComputerSnapshot(sandbox, threadId, snapshots)
+        }
         // A kept sandbox outlives its thread. The provider timeout ends it.
-        if (sandboxIds) return driver
-        return { ...driver, close: () => sandbox.destroy() }
+        if (sandboxIds && !snapshots) return driver
+        return {
+          ...driver,
+          close: async () => {
+            try {
+              if (snapshots) {
+                await saveComputerSnapshot(sandbox, threadId, snapshots)
+              }
+            } finally {
+              if (!sandboxIds) await sandbox.destroy()
+            }
+          },
+        }
       } catch (error) {
         // A kept sandbox holds the state of the thread, like a signed-in
         // browser. Keep it, so the next call of the thread tries it again.
@@ -313,3 +360,71 @@ async function destroyAfterFailure(sandbox: SandboxHandle) {
     )
   })
 }
+
+/**
+ * Save the files of `snapshots.root` as the newest snapshot of the thread.
+ * `sandboxComputer` calls it when a thread closes or goes idle. Call it
+ * yourself after a step that you must keep, like a sign-in.
+ */
+export async function saveComputerSnapshot(
+  sandbox: SandboxHandle,
+  threadId: string,
+  { store, root, policy, before, after }: SandboxComputerSnapshots,
+) {
+  await before?.(sandbox)
+  try {
+    const { files } = await captureSandboxFiles(
+      sandbox,
+      { blobs: store.persistence.stores.blobs, workspaceRoot: root },
+      policy,
+    )
+    const writer = await store.checkpoints.acquireWriter(threadId)
+    try {
+      const parentCheckpointId = await store.checkpoints.getHead(threadId)
+      await store.checkpoints.append({
+        checkpoint: {
+          id: crypto.randomUUID(),
+          threadId,
+          parentCheckpointId,
+          createdAt: Date.now(),
+          reason: 'named',
+          label: 'computer',
+          files,
+          conversation: [],
+          artifacts: [],
+        },
+        expectedHeadId: parentCheckpointId,
+        writer,
+      })
+    } finally {
+      await writer.release()
+    }
+  } finally {
+    await after?.(sandbox)
+  }
+}
+
+/** Restore the newest snapshot of the thread into a new sandbox. */
+async function restoreComputerSnapshot(
+  sandbox: SandboxHandle,
+  threadId: string,
+  { store, root, policy, before, after }: SandboxComputerSnapshots,
+) {
+  const head = await store.checkpoints.getHead(threadId)
+  if (head === null) return
+  const checkpoint = await store.checkpoints.get(head)
+  if (!checkpoint) {
+    throw new Error(`The snapshot ${head} of thread ${threadId} is missing.`)
+  }
+  await before?.(sandbox)
+  try {
+    await restoreSandboxFiles(
+      sandbox,
+      { blobs: store.persistence.stores.blobs, workspaceRoot: root },
+      checkpoint,
+      policy,
+    )
+  } finally {
+    await after?.(sandbox)
+  }
+}
diff --git a/packages/ai-computer-sandbox/src/index.ts b/packages/ai-computer-sandbox/src/index.ts
index 3abdf74673..525b1dccae 100644
--- a/packages/ai-computer-sandbox/src/index.ts
+++ b/packages/ai-computer-sandbox/src/index.ts
@@ -1,6 +1,8 @@
 export {
   createSandboxComputerDriver,
   sandboxComputer,
+  saveComputerSnapshot,
   type SandboxComputerDriverOptions,
   type SandboxComputerOptions,
+  type SandboxComputerSnapshots,
 } from './driver'
diff --git a/packages/ai-computer-sandbox/tests/driver.test.ts b/packages/ai-computer-sandbox/tests/driver.test.ts
index 785773d5f7..49aff0488b 100644
--- a/packages/ai-computer-sandbox/tests/driver.test.ts
+++ b/packages/ai-computer-sandbox/tests/driver.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
+import { memorySandboxSnapshots } from '@tanstack/ai-sandbox'
 import { createSandboxComputerDriver, sandboxComputer } from '../src/index'
 import type {
   ExecResult,
@@ -18,12 +19,19 @@ interface FakeOptions {
   missing?: Array<string>
   /** The size xdpyinfo reports. */
   size?: string
+  /** The files of the sandbox, by absolute path. */
+  files?: Record<string, string>
 }
 
 let sandboxCount = 0
 
 /** A fake sandbox. Each command adds one line to `calls`, prefixed with `exec` or `spawn`. */
-function fakeSandbox({ running = true, missing = [], size }: FakeOptions = {}) {
+function fakeSandbox({
+  running = true,
+  missing = [],
+  size,
+  files = {},
+}: FakeOptions = {}) {
   const calls: Array<string> = []
   let started = running
   const ok = (stdout = ''): ExecResult => ({ stdout, stderr: '', exitCode: 0 })
@@ -50,12 +58,67 @@ function fakeSandbox({ running = true, missing = [], size }: FakeOptions = {}) {
   const destroy = vi.fn(async () => {
     calls.push('destroy')
   })
+  const fs = memoryFs(files)
   const sandbox = {
     id: `sbx-${++sandboxCount}`,
     process: { exec, spawn },
+    fs,
     destroy,
   } as unknown as SandboxHandle
-  return { sandbox, calls, exec, destroy }
+  return { sandbox, calls, exec, destroy, files: fs.files }
+}
+
+/** An in-memory file system with the methods that snapshots use. */
+function memoryFs(initial: Record<string, string>) {
+  const encoder = new TextEncoder()
+  const files = new Map<string, Uint8Array>(
+    Object.entries(initial).map(([path, text]) => [path, encoder.encode(text)]),
+  )
+  const dirs = new Set<string>()
+  for (const path of files.keys()) {
+    const parts = path.split('/')
+    for (let i = 2; i < parts.length; i++) dirs.add(parts.slice(0, i).join('/'))
+  }
+  const children = (dir: string) => [
+    ...new Set(
+      [...files.keys(), ...dirs]
+        .filter((path) => path.startsWith(`${dir}/`))
+        .map((path) => path.slice(dir.length + 1).split('/')[0] ?? ''),
+    ),
+  ]
+  return {
+    files,
+    lstat: async (path: string) => {
+      const bytes = files.get(path)
+      if (bytes) return { type: 'file', mode: 0o100644, size: bytes.byteLength }
+      return dirs.has(path) ? { type: 'dir', mode: 0o40755 } : undefined
+    },
+    list: async (dir: string) =>
+      children(dir).map((name) => ({
+        name,
+        path: `${dir}/${name}`,
+        type: dirs.has(`${dir}/${name}`) ? 'dir' : 'file',
+      })),
+    readBytes: async (path: string) => {
+      const bytes = files.get(path)
+      if (!bytes) throw new Error(`No file ${path}`)
+      return bytes
+    },
+    write: async (path: string, data: Uint8Array) => {
+      files.set(path, data)
+    },
+    mkdir: async (path: string) => {
+      dirs.add(path)
+    },
+    remove: async (path: string) => {
+      for (const key of [...files.keys(), ...dirs]) {
+        if (key === path || key.startsWith(`${path}/`)) {
+          files.delete(key)
+          dirs.delete(key)
+        }
+      }
+    },
+  }
 }
 
 /** A driver on a sandbox whose display already runs. `calls` holds only the actions. */
@@ -327,4 +390,66 @@ describe('sandboxComputer', () => {
     expect(provider.resume).toHaveBeenCalledWith({ id: 'gone' })
     expect(sandboxIds.ids.get('a')).toBe(created.sandbox.id)
   })
+
+  it('with snapshots, saves the folder on close and restores it into the next new sandbox', async () => {
+    const first = fakeSandbox({
+      files: { '/p/Cookies': 'signed-in', '/p/Cache/data': 'big' },
+    })
+    const second = fakeSandbox({ files: { '/p/Cookies': 'new' } })
+    const log: Array<string> = []
+    const factory = sandboxComputer({
+      provider: fakeProvider([first, second]),
+      snapshots: {
+        store: await memorySandboxSnapshots(),
+        root: '/p',
+        policy: { exclude: (path) => path.split('/')[0] === 'Cache' },
+        before: async (sandbox) => {
+          log.push(`before ${sandbox.id}`)
+        },
+        after: async (sandbox) => {
+          log.push(`after ${sandbox.id}`)
+        },
+      },
+    })
+
+    const driver = await factory.create({ threadId: 'a' })
+    // A thread with no snapshot restores nothing.
+    expect(log).toEqual([])
+    await driver.close?.()
+    expect(first.destroy).toHaveBeenCalled()
+
+    await factory.create({ threadId: 'a' })
+    const { id: firstId } = first.sandbox
+    const { id: secondId } = second.sandbox
+    expect(log).toEqual([
+      `before ${firstId}`,
+      `after ${firstId}`,
+      `before ${secondId}`,
+      `after ${secondId}`,
+    ])
+    expect(new TextDecoder().decode(second.files.get('/p/Cookies'))).toBe(
+      'signed-in',
+    )
+    expect(second.files.has('/p/Cache/data')).toBe(false)
+  })
+
+  it('with snapshots and sandboxIds, saves on close but restores nothing into a resumed sandbox', async () => {
+    const kept = fakeSandbox({ files: { '/p/Cookies': 'live' } })
+    const store = await memorySandboxSnapshots()
+    const factory = sandboxComputer({
+      provider: fakeProvider([], [kept]),
+      sandboxIds: memoryIds({ a: kept.sandbox.id }),
+      snapshots: { store, root: '/p' },
+    })
+    const driver = await factory.create({ threadId: 'a' })
+    await driver.close?.()
+    expect(kept.destroy).not.toHaveBeenCalled()
+    const head = await store.checkpoints.getHead('a')
+    expect(head).not.toBeNull()
+
+    // A second resume keeps the live files, with no restore.
+    kept.files.set('/p/Cookies', new TextEncoder().encode('newer'))
+    await factory.create({ threadId: 'a' })
+    expect(new TextDecoder().decode(kept.files.get('/p/Cookies'))).toBe('newer')
+  })
 })
diff --git a/packages/ai-sandbox/src/index.ts b/packages/ai-sandbox/src/index.ts
index d89c7b65b6..3443dd3aa7 100644
--- a/packages/ai-sandbox/src/index.ts
+++ b/packages/ai-sandbox/src/index.ts
@@ -60,7 +60,12 @@ export type {
 } from './checkpoint-store'
 
 // File snapshot policy used by provider snapshot create/restore inputs.
-export { SandboxSnapshotError, defaultSandboxSnapshotPolicy } from './snapshots'
+export {
+  SandboxSnapshotError,
+  captureSandboxFiles,
+  defaultSandboxSnapshotPolicy,
+  restoreSandboxFiles,
+} from './snapshots'
 export type {
   SandboxSnapshotErrorCode,
   SandboxSnapshotPolicy,

From 3ef300cb1ec322f49a7cb87cafa97a0dab949392 Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Tue, 3 Nov 2026 17:47:34 +0700
Subject: [PATCH 5/7] feat(examples): keep the computer-use-login sign-in with
 profile snapshots

---
 docs/tutorials/computer-use-login.md          | 90 ++++++++++++++++---
 examples/react/computer-use-login/README.md   | 18 ++--
 .../react/computer-use-login/package.json     |  1 +
 .../computer-use-login/sandbox/Dockerfile     |  4 +-
 .../computer-use-login/sandbox/browser.sh     | 41 +++++++++
 .../computer-use-login/sandbox/desktop.sh     |  9 +-
 .../computer-use-login/sandbox/policy.json    |  3 +-
 .../react/computer-use-login/src/harness.ts   | 58 ++++++++++--
 pnpm-lock.yaml                                |  3 +
 9 files changed, 196 insertions(+), 31 deletions(-)
 create mode 100755 examples/react/computer-use-login/sandbox/browser.sh

diff --git a/docs/tutorials/computer-use-login.md b/docs/tutorials/computer-use-login.md
index 7080698223..0d866f7126 100644
--- a/docs/tutorials/computer-use-login.md
+++ b/docs/tutorials/computer-use-login.md
@@ -29,7 +29,7 @@ Pick React. Then install the packages:
 
 <!-- ::start:tabs variant="package-manager" mode="install" -->
 
-react: @tanstack/ai @tanstack/ai-react @tanstack/ai-openai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-computer-use @tanstack/ai-computer-sandbox @tanstack/ai-sandbox-docker zod
+react: @tanstack/ai @tanstack/ai-react @tanstack/ai-openai @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-computer-use @tanstack/ai-computer-sandbox @tanstack/ai-sandbox @tanstack/ai-sandbox-docker zod
 
 <!-- ::end:tabs -->
 
@@ -49,7 +49,7 @@ The approval of a tool call goes into the harness log. So the card approves the
 
 ## 2. Build the desktop
 
-Create a `sandbox` folder in your app with four files.
+Create a `sandbox` folder in your app with five files.
 
 `sandbox/Dockerfile` installs the screen, the tools of the sandbox computer driver, Chromium, and Python:
 
@@ -64,8 +64,8 @@ RUN printf 'Acquire::Retries "10";\nAcquire::ForceIPv4 "true";\n' > /etc/apt/apt
   && rm -rf /var/lib/apt/lists/*
 
 COPY policy.json /etc/chromium/policies/managed/policy.json
-COPY desktop.sh login.py /opt/desktop/
-RUN chmod +x /opt/desktop/desktop.sh
+COPY desktop.sh browser.sh login.py /opt/desktop/
+RUN chmod +x /opt/desktop/desktop.sh /opt/desktop/browser.sh
 ```
 
 `sandbox/policy.json` keeps passwords off the screen. The model sees the screen and moves the mouse, so Chromium must not offer to show a saved password:
@@ -75,10 +75,13 @@ RUN chmod +x /opt/desktop/desktop.sh
   "PasswordManagerEnabled": false,
   "AutofillAddressEnabled": false,
   "AutofillCreditCardEnabled": false,
-  "URLBlocklist": ["javascript://*"]
+  "URLBlocklist": ["javascript://*"],
+  "RestoreOnStartup": 1
 }
 ```
 
+`RestoreOnStartup` opens the last tabs when Chromium starts again. It also keeps the session cookies, so a restarted Chromium is still signed in.
+
 `sandbox/desktop.sh` is the main process of the container. It starts the screen and Chromium:
 
 ```bash
@@ -88,19 +91,27 @@ Xvfb :0 -ac -screen 0 1024x768x24 -nolisten tcp &
 until DISPLAY=:0 xdpyinfo >/dev/null 2>&1; do sleep 0.2; done
 
 while true; do
+  # browser.sh stop pauses this loop while a snapshot saves or restores the profile.
+  while [ -e /tmp/chromium-paused ]; do sleep 0.2; done
   # --no-sandbox: Chromium runs as root in the container, which is the sandbox.
   DISPLAY=:0 chromium --no-sandbox --test-type --no-first-run \
     --no-default-browser-check --disable-dev-shm-usage \
-    --user-data-dir=/root/chromium-profile \
+    --user-data-dir=/root/chromium-profile --password-store=basic \
     --remote-debugging-port=9222 \
-    --window-position=0,0 --window-size=1024,768 about:blank
+    --window-position=0,0 --window-size=1024,768
   sleep 1
 done
 ```
 
 - `--user-data-dir` keeps the cookies. A restarted container is still signed in.
+- `--password-store=basic` uses the same cookie key in every container. A profile that a new container restores can read its cookies.
 - `--remote-debugging-port` listens on 127.0.0.1 inside the container only. No port leaves the container.
 
+`sandbox/browser.sh` stops and starts Chromium, so a snapshot saves a complete profile. Copy it from the [example](https://github.com/TanStack/ai/blob/main/examples/react/computer-use-login/sandbox/browser.sh):
+
+- `browser.sh stop` pauses the loop in `desktop.sh`, then closes Chromium with the debugging command `Browser.close`. A clean close writes the cookies to disk. A kill signal can lose them.
+- `browser.sh start` ends the pause, then waits until Chromium answers on its debugging port.
+
 `sandbox/login.py` signs in. Copy it from the [example](https://github.com/TanStack/ai/blob/main/examples/react/computer-use-login/sandbox/login.py). It reads the site, the username, and the password from its environment, then talks to Chromium over the debugging port:
 
 1. It opens the site in the current tab.
@@ -140,7 +151,7 @@ export const requestLoginTool = toolDefinition({
 
 ## 4. Set up the harness
 
-Create `src/harness.ts`. It has the Docker provider, two stores, the tool, and the harness.
+Create `src/harness.ts`. It has the Docker provider, three stores, the tool, and the harness.
 
 First the provider and the sandbox ids. `sandboxIds` keeps the container of each thread, so the thread finds its signed-in browser again later:
 
@@ -151,7 +162,12 @@ import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
 import { permissions } from '@tanstack/ai-harness/plugins'
 import { createHarnessHandler } from '@tanstack/ai-harness/server'
 import { computerUse } from '@tanstack/ai-computer-use/harness'
-import { sandboxComputer } from '@tanstack/ai-computer-sandbox'
+import {
+  saveComputerSnapshot,
+  sandboxComputer,
+} from '@tanstack/ai-computer-sandbox'
+import { memorySandboxSnapshots } from '@tanstack/ai-sandbox'
+import type { SandboxHandle } from '@tanstack/ai-sandbox'
 import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
 import { openaiText } from '@tanstack/ai-openai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
@@ -198,6 +214,49 @@ const sandboxIds = {
 }
 ```
 
+Then the snapshots of the Chromium profile. `sandboxIds` brings back a container that still exists. A snapshot brings the profile into a new container, when the old one is gone. This also works with providers whose disk does not last, like Cloudflare:
+
+```typescript ignore
+const PROFILE = '/root/chromium-profile'
+// Only the files that keep a sign-in. Caches stay out of the snapshot.
+const PROFILE_FILES = [
+  'Local State',
+  'Default/Cookies',
+  'Default/Cookies-journal',
+  'Default/Preferences',
+  'Default/Sessions',
+  'Default/Local Storage',
+  'Default/Session Storage',
+]
+const keepInProfile = (path: string) =>
+  PROFILE_FILES.some(
+    (file) =>
+      path === file ||
+      path.startsWith(`${file}/`) ||
+      file.startsWith(`${path}/`),
+  )
+
+async function browser(sandbox: SandboxHandle, action: 'stop' | 'start') {
+  const result = await sandbox.process.exec(`/opt/desktop/browser.sh ${action}`)
+  if (result.exitCode !== 0) {
+    throw new Error(`Could not ${action} Chromium: ${result.stderr.trim()}`)
+  }
+}
+
+const snapshots = {
+  store: await memorySandboxSnapshots(),
+  root: PROFILE,
+  policy: { exclude: (path: string) => !keepInProfile(path) },
+  // Chromium writes its profile all the time. Stop it, so the files are complete.
+  before: (sandbox: SandboxHandle) => browser(sandbox, 'stop'),
+  after: (sandbox: SandboxHandle) => browser(sandbox, 'start'),
+}
+```
+
+- The driver saves the profile when a thread closes or goes idle. The tool below also saves it right after a sign-in.
+- `memorySandboxSnapshots()` keeps the snapshots in memory, like the chat. For a user who comes back the next day, build the stores with `createSandboxSnapshots` on your database.
+- The profile holds session cookies. Keep the blob store secret, and encrypt it in production.
+
 Then the logins. The card sends a login, and the tool takes it once. A login that nobody takes is deleted after 5 minutes:
 
 ```typescript ignore
@@ -279,9 +338,12 @@ const requestLogin = requestLoginTool.server(async ({ site }, context) => {
     throw new Error(`The sign-in failed: ${result.stderr.trim()}`)
   }
   const page = loginResultSchema.parse(JSON.parse(result.stdout))
-  return page.hasPasswordField
-    ? `The form was sent, but ${page.url} still shows a password field. The sign-in may have failed. Take a screenshot to check.`
-    : `Signed in. The browser shows ${page.url}. Take a screenshot to see it.`
+  if (page.hasPasswordField) {
+    return `The form was sent, but ${page.url} still shows a password field. The sign-in may have failed. Take a screenshot to check.`
+  }
+  // Save the signed-in profile now. A server that stops skips the idle save.
+  await saveComputerSnapshot(sandbox, threadId, snapshots)
+  return `Signed in. The browser shows ${page.url}. Take a screenshot to see it.`
 })
 ```
 
@@ -292,7 +354,7 @@ Last, the harness and its HTTP handler:
 
 ```typescript ignore
 const computer = computerUse({
-  driver: sandboxComputer({ provider, sandboxIds }),
+  driver: sandboxComputer({ provider, sandboxIds, snapshots }),
   screenshotDelay: 1000,
 })
 
@@ -315,7 +377,7 @@ export const handler = createHarnessHandler({
 })
 ```
 
-- `sandboxComputer` makes one container for each thread. With `sandboxIds`, it keeps the container and reconnects to it later.
+- `sandboxComputer` makes one container for each thread. With `sandboxIds`, it keeps the container and reconnects to it later. With `snapshots`, a new container gets the saved profile.
 - `memoryPersistence()` keeps the chat in memory. A server restart loses the chat, but not the container. For a user who comes back the next day, use a persistence store in your database. See [Chat persistence](../persistence/chat-persistence).
 - `openAccess` serves every request with no login. Use it only on your own machine. See [Serve with no login](../harness/access#serve-with-no-login).
 
diff --git a/examples/react/computer-use-login/README.md b/examples/react/computer-use-login/README.md
index 9c34e2b06d..4e81988fc8 100644
--- a/examples/react/computer-use-login/README.md
+++ b/examples/react/computer-use-login/README.md
@@ -2,7 +2,7 @@
 
 Your agent uses a desktop, and a site asks it for a password. In this app, the model calls `requestLogin`. You type the username and password in a card in the chat. The server fills the form in the browser, and the model never sees the password.
 
-The desktop is a Docker container with Chromium on it. Each chat thread keeps its own container, so it stays signed in when you come back later.
+The desktop is a Docker container with Chromium on it. Each chat thread keeps its own container, so it stays signed in when you come back later. The app also saves the Chromium profile after each sign-in. When the container of a thread is gone, a new container gets the profile back, still signed in.
 
 ## Run it
 
@@ -22,17 +22,18 @@ The model opens a practice sign-in page. When the login card shows, type `tomsmi
 3. The card then approves the tool call. The approval is only "yes". The harness writes approvals to its log, so a password must never be in one.
 4. The tool takes the login from memory and deletes it. It runs `sandbox/login.py` in the container, with the password in the environment of that one process, not on its command line.
 5. The script opens the site in Chromium and checks its origin. It fills the username and the password field, then submits the form. Then it clears every password field.
-6. The model gets "Signed in" and the address of the page.
+6. The tool saves a snapshot of the Chromium profile, with the cookies of the sign-in.
+7. The model gets "Signed in" and the address of the page.
 
 The model sees the screen, so Chromium must never show a password. `sandbox/policy.json` turns off the password manager and `javascript:` URLs. Chromium listens for its debugging protocol only inside the container. No port leaves it.
 
 ## Files
 
-- `src/harness.ts`: the harness, the Docker provider, the `requestLogin` tool, and the two stores.
+- `src/harness.ts`: the harness, the Docker provider, the `requestLogin` tool, and the three stores.
 - `src/request-login.ts`: the tool definition that the server and the browser share.
 - `src/routes/api.login.ts`: the route that takes the username and password.
 - `src/routes/index.tsx`: the chat and the login card.
-- `sandbox/`: the desktop image. `desktop.sh` starts the screen and Chromium. `login.py` fills the form.
+- `sandbox/`: the desktop image. `desktop.sh` starts the screen and Chromium. `browser.sh` stops and starts Chromium for a snapshot. `login.py` fills the form.
 
 ## Run it on a server
 
@@ -47,16 +48,19 @@ const provider = e2bSandbox({
 })
 ```
 
-Build an E2B template from `sandbox/Dockerfile`, and start `desktop.sh` in it. Then move the two stores of `src/harness.ts` to your database: the sandbox id of each thread, and the logins (with a time limit).
+Build an E2B template from `sandbox/Dockerfile`, and start `desktop.sh` in it. Then move the three stores of `src/harness.ts` to your database:
+
+- The sandbox id of each thread.
+- The profile snapshots. Build them with `createSandboxSnapshots`. They hold session cookies, so encrypt them.
+- The logins, with a time limit.
 
 This app keeps the chat in `memoryPersistence()`. When the server restarts, the chat is gone, but the container stays. For a user who comes back the next day, give `createHarnessHost` a persistence store in your database. See [Chat persistence](https://tanstack.com/ai/latest/docs/persistence/chat-persistence).
 
-Cloudflare containers do not fit this app. Their disk is empty after each restart, so the browser signs out.
+A provider whose disk does not last, like Cloudflare, also keeps the sign-in. Each new container gets the profile snapshot back.
 
 ## Not in this app
 
 - Two-factor codes.
 - A live view of the desktop for a captcha.
-- A saved Chromium profile in sandbox snapshots.
 
 CAUTION: The harness route has no login, and the browser can open every address that your server can reach. Run this app only on your own machine.
diff --git a/examples/react/computer-use-login/package.json b/examples/react/computer-use-login/package.json
index 188c29a97a..06579dbaf2 100644
--- a/examples/react/computer-use-login/package.json
+++ b/examples/react/computer-use-login/package.json
@@ -17,6 +17,7 @@
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-react": "workspace:*",
+    "@tanstack/ai-sandbox": "workspace:*",
     "@tanstack/ai-sandbox-docker": "workspace:*",
     "@tanstack/react-router": "^1.170.41",
     "@tanstack/react-start": "^1.168.60",
diff --git a/examples/react/computer-use-login/sandbox/Dockerfile b/examples/react/computer-use-login/sandbox/Dockerfile
index 44ded1822d..74a4c2b821 100644
--- a/examples/react/computer-use-login/sandbox/Dockerfile
+++ b/examples/react/computer-use-login/sandbox/Dockerfile
@@ -14,5 +14,5 @@ RUN printf 'Acquire::Retries "10";\nAcquire::ForceIPv4 "true";\n' > /etc/apt/apt
 # a password: no password manager, and no `javascript:` URLs.
 # (A DevTools policy would also close the debugging port that login.py uses.)
 COPY policy.json /etc/chromium/policies/managed/policy.json
-COPY desktop.sh login.py /opt/desktop/
-RUN chmod +x /opt/desktop/desktop.sh
+COPY desktop.sh browser.sh login.py /opt/desktop/
+RUN chmod +x /opt/desktop/desktop.sh /opt/desktop/browser.sh
diff --git a/examples/react/computer-use-login/sandbox/browser.sh b/examples/react/computer-use-login/sandbox/browser.sh
new file mode 100755
index 0000000000..4c3c7012d9
--- /dev/null
+++ b/examples/react/computer-use-login/sandbox/browser.sh
@@ -0,0 +1,41 @@
+#!/bin/sh
+# Stop or start Chromium, so a snapshot saves or restores a complete profile.
+# `stop` pauses the loop in desktop.sh, then waits until Chromium has exited.
+# `start` ends the pause, then waits until Chromium answers on its debugging port.
+set -e
+PAUSE=/tmp/chromium-paused
+case "$1" in
+  stop)
+    mkdir -p /root/chromium-profile
+    touch "$PAUSE"
+    # Browser.close is a clean exit: Chromium writes its cookies to disk.
+    # A signal (pkill) skips that, and the session cookies are lost.
+    if pgrep -x chromium >/dev/null; then
+      python3 - <<'PY'
+import asyncio, json, urllib.request, websockets
+url = json.load(urllib.request.urlopen("http://127.0.0.1:9222/json/version"))["webSocketDebuggerUrl"]
+async def close():
+    async with websockets.connect(url) as socket:
+        await socket.send(json.dumps({"id": 1, "method": "Browser.close"}))
+        await socket.recv()
+asyncio.run(close())
+PY
+    fi
+    for i in $(seq 100); do pgrep -x chromium >/dev/null || exit 0; sleep 0.2; done
+    echo 'Chromium did not stop.' >&2
+    exit 1
+    ;;
+  start)
+    rm -f "$PAUSE"
+    for i in $(seq 150); do
+      python3 -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:9222/json/version')" 2>/dev/null && exit 0
+      sleep 0.2
+    done
+    echo 'Chromium did not start.' >&2
+    exit 1
+    ;;
+  *)
+    echo 'Use: browser.sh stop|start' >&2
+    exit 2
+    ;;
+esac
diff --git a/examples/react/computer-use-login/sandbox/desktop.sh b/examples/react/computer-use-login/sandbox/desktop.sh
index 2160d62e17..9d973ab2ff 100644
--- a/examples/react/computer-use-login/sandbox/desktop.sh
+++ b/examples/react/computer-use-login/sandbox/desktop.sh
@@ -9,11 +9,16 @@ Xvfb :0 -ac -screen 0 1024x768x24 -nolisten tcp &
 until DISPLAY=:0 xdpyinfo >/dev/null 2>&1; do sleep 0.2; done
 
 while true; do
+  # browser.sh stop pauses this loop while a snapshot saves or restores the profile.
+  # With no address, Chromium opens the tabs of its last session (RestoreOnStartup).
+  while [ -e /tmp/chromium-paused ]; do sleep 0.2; done
+  # --password-store=basic: the cookie key is the same in every container, so
+  # a restored profile can read its cookies.
   # --no-sandbox: Chromium runs as root in the container, which is the sandbox.
   DISPLAY=:0 chromium --no-sandbox --test-type --no-first-run \
     --no-default-browser-check --disable-dev-shm-usage \
-    --user-data-dir=/root/chromium-profile \
+    --user-data-dir=/root/chromium-profile --password-store=basic \
     --remote-debugging-port=9222 \
-    --window-position=0,0 --window-size=1024,768 about:blank
+    --window-position=0,0 --window-size=1024,768
   sleep 1
 done
diff --git a/examples/react/computer-use-login/sandbox/policy.json b/examples/react/computer-use-login/sandbox/policy.json
index 05e27b20b0..3622b26985 100644
--- a/examples/react/computer-use-login/sandbox/policy.json
+++ b/examples/react/computer-use-login/sandbox/policy.json
@@ -2,5 +2,6 @@
   "PasswordManagerEnabled": false,
   "AutofillAddressEnabled": false,
   "AutofillCreditCardEnabled": false,
-  "URLBlocklist": ["javascript://*"]
+  "URLBlocklist": ["javascript://*"],
+  "RestoreOnStartup": 1
 }
diff --git a/examples/react/computer-use-login/src/harness.ts b/examples/react/computer-use-login/src/harness.ts
index 330e481f6b..ba41244595 100644
--- a/examples/react/computer-use-login/src/harness.ts
+++ b/examples/react/computer-use-login/src/harness.ts
@@ -4,7 +4,12 @@ import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
 import { permissions } from '@tanstack/ai-harness/plugins'
 import { createHarnessHandler } from '@tanstack/ai-harness/server'
 import { computerUse } from '@tanstack/ai-computer-use/harness'
-import { sandboxComputer } from '@tanstack/ai-computer-sandbox'
+import {
+  saveComputerSnapshot,
+  sandboxComputer,
+} from '@tanstack/ai-computer-sandbox'
+import { memorySandboxSnapshots } from '@tanstack/ai-sandbox'
+import type { SandboxHandle } from '@tanstack/ai-sandbox'
 import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
 import { openaiText } from '@tanstack/ai-openai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
@@ -54,6 +59,46 @@ const sandboxIds = {
   },
 }
 
+// The Chromium profile of each thread, saved after a sign-in and when the
+// thread goes idle. A thread whose container is gone gets a new container
+// with this profile, so it is still signed in.
+// ponytail: memory only, like the chat. Use durable stores to keep a sign-in
+// after a server restart. The profile holds session cookies: keep it secret.
+const PROFILE = '/root/chromium-profile'
+// Only the files that keep a sign-in. Caches stay out of the snapshot.
+const PROFILE_FILES = [
+  'Local State',
+  'Default/Cookies',
+  'Default/Cookies-journal',
+  'Default/Preferences',
+  'Default/Sessions',
+  'Default/Local Storage',
+  'Default/Session Storage',
+]
+const keepInProfile = (path: string) =>
+  PROFILE_FILES.some(
+    (file) =>
+      path === file ||
+      path.startsWith(`${file}/`) ||
+      file.startsWith(`${path}/`),
+  )
+
+async function browser(sandbox: SandboxHandle, action: 'stop' | 'start') {
+  const result = await sandbox.process.exec(`/opt/desktop/browser.sh ${action}`)
+  if (result.exitCode !== 0) {
+    throw new Error(`Could not ${action} Chromium: ${result.stderr.trim()}`)
+  }
+}
+
+const snapshots = {
+  store: await memorySandboxSnapshots(),
+  root: PROFILE,
+  policy: { exclude: (path: string) => !keepInProfile(path) },
+  // Chromium writes its profile all the time. Stop it, so the files are complete.
+  before: (sandbox: SandboxHandle) => browser(sandbox, 'stop'),
+  after: (sandbox: SandboxHandle) => browser(sandbox, 'start'),
+}
+
 // The username and password of each thread, between the login card and the
 // sign-in. Only in memory, and never in a log.
 // ponytail: one process. With more servers, use a store with a time limit.
@@ -135,14 +180,17 @@ const requestLogin = requestLoginTool.server(async ({ site }, context) => {
     throw new Error(`The sign-in failed: ${result.stderr.trim()}`)
   }
   const page = loginResultSchema.parse(JSON.parse(result.stdout))
-  return page.hasPasswordField
-    ? `The form was sent, but ${page.url} still shows a password field. The sign-in may have failed. Take a screenshot to check.`
-    : `Signed in. The browser shows ${page.url}. Take a screenshot to see it.`
+  if (page.hasPasswordField) {
+    return `The form was sent, but ${page.url} still shows a password field. The sign-in may have failed. Take a screenshot to check.`
+  }
+  // Save the signed-in profile now. A server that stops skips the idle save.
+  await saveComputerSnapshot(sandbox, threadId, snapshots)
+  return `Signed in. The browser shows ${page.url}. Take a screenshot to see it.`
 })
 
 // One time, outside `plugins`, so every session shares the containers.
 const computer = computerUse({
-  driver: sandboxComputer({ provider, sandboxIds }),
+  driver: sandboxComputer({ provider, sandboxIds, snapshots }),
   // Pages load in a real browser. Give each one time to draw.
   screenshotDelay: 1000,
 })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bc6a0042e8..c07f558995 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -353,6 +353,9 @@ importers:
       '@tanstack/ai-react':
         specifier: workspace:*
         version: link:../../../packages/ai-react
+      '@tanstack/ai-sandbox':
+        specifier: workspace:*
+        version: link:../../../packages/ai-sandbox
       '@tanstack/ai-sandbox-docker':
         specifier: workspace:*
         version: link:../../../packages/ai-sandbox-docker

From 6f8f6fdd83d41e7d26517837543ad09bb2adbcd5 Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Wed, 4 Nov 2026 09:06:22 +1100
Subject: [PATCH 6/7] fix(ai-sandbox-docker): publish ports on 127.0.0.1 only

Docker published publishPorts on every network interface, so other
computers on the network could reach a sandbox port.
---
 .changeset/docker-publish-localhost.md     |  5 +++++
 docs/sandbox/providers-advanced.md         |  1 +
 packages/ai-sandbox-docker/src/handle.ts   |  2 +-
 packages/ai-sandbox-docker/src/provider.ts | 10 +++++++---
 4 files changed, 14 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/docker-publish-localhost.md

diff --git a/.changeset/docker-publish-localhost.md b/.changeset/docker-publish-localhost.md
new file mode 100644
index 0000000000..2e08c6408a
--- /dev/null
+++ b/.changeset/docker-publish-localhost.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-sandbox-docker': patch
+---
+
+`publishPorts` now publishes each port on 127.0.0.1 only, and `ports.connect` returns a `http://127.0.0.1:<port>` address. Before, Docker published the ports on every network interface, so other computers on the network could connect.
diff --git a/docs/sandbox/providers-advanced.md b/docs/sandbox/providers-advanced.md
index 68479eeb81..4bdb2fdd8e 100644
--- a/docs/sandbox/providers-advanced.md
+++ b/docs/sandbox/providers-advanced.md
@@ -87,6 +87,7 @@ const isolated = dockerSandbox({ image: 'node:22' })
 - **Workspace:** when `workspace.source` is `localSource(dir)`, `create()` copies the folder into `workdir` (`/workspace` by default). The copy has every file that git does not ignore, with its uncommitted changes, and the history of the current branch. The folder must be a git repository root (not a shallow clone), and the host and the image need `git`. Fork, restore, and resume do not copy the folder again. See [Copy your project into the container](../harness/coding-tools-backends#copy-your-project-into-the-container).
 - **Auth and env:** no host login. Pass credentials as workspace secrets. They go into the container env at create and resume.
 - **Tools:** the agent reaches host tools at `host.docker.internal`. See [Tools](./tools).
+- **Ports:** pass `publishPorts: [port]` to `dockerSandbox()`. Docker publishes each port on 127.0.0.1 only, so other computers cannot connect. `ports.connect(port)` returns `http://127.0.0.1:<host port>`.
 - **Snapshot and resume:** full commit-based snapshots, `fork`, and resume by id. Bootstrap takes a snapshot after `setup`, so later runs resume from it and skip setup.
 
 ## Docker Sandboxes (sbx)
diff --git a/packages/ai-sandbox-docker/src/handle.ts b/packages/ai-sandbox-docker/src/handle.ts
index 9f5619062c..2fe576aa62 100644
--- a/packages/ai-sandbox-docker/src/handle.ts
+++ b/packages/ai-sandbox-docker/src/handle.ts
@@ -808,7 +808,7 @@ export class DockerHandle implements SandboxHandle {
         `docker: container port ${port} is not published. Pass publishPorts: [${port}] to dockerSandbox() to reach it from the host.`,
       )
     }
-    return { url: `http://localhost:${hostPort}` }
+    return { url: `http://127.0.0.1:${hostPort}` }
   }
 
   async snapshot(label?: string): Promise<SnapshotRef> {
diff --git a/packages/ai-sandbox-docker/src/provider.ts b/packages/ai-sandbox-docker/src/provider.ts
index efcd2b0a3b..afceb0ca4f 100644
--- a/packages/ai-sandbox-docker/src/provider.ts
+++ b/packages/ai-sandbox-docker/src/provider.ts
@@ -22,7 +22,7 @@ export interface DockerSandboxConfig {
   dockerodeOptions?: Dockerode.DockerOptions
   /** Command that keeps the container alive. Defaults to `tail -f /dev/null`. */
   keepAliveCommand?: Array<string>
-  /** Container ports to publish to the host (for `ports.connect`). */
+  /** Container ports to publish on the host at 127.0.0.1 (for `ports.connect`). */
   publishPorts?: Array<number>
   /**
    * Add `host.docker.internal:host-gateway` so the container can reach the
@@ -100,10 +100,14 @@ class DockerProvider implements SandboxProvider {
   ): Promise<SandboxHandle> {
     const { env } = options
     const exposed: Record<string, Record<string, never>> = {}
-    const bindings: Record<string, Array<{ HostPort: string }>> = {}
+    const bindings: Record<
+      string,
+      Array<{ HostIp: string; HostPort: string }>
+    > = {}
     for (const port of this.config.publishPorts ?? []) {
       exposed[`${port}/tcp`] = {}
-      bindings[`${port}/tcp`] = [{ HostPort: '' }] // let Docker pick a free host port
+      // Only this machine can connect. Docker picks a free host port.
+      bindings[`${port}/tcp`] = [{ HostIp: '127.0.0.1', HostPort: '' }]
     }
 
     const container = await this.docker.createContainer({

From 4283521de0817a5f81e5d006e9fd8882d59be870 Mon Sep 17 00:00:00 2001
From: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com>
Date: Wed, 4 Nov 2026 09:06:22 +1100
Subject: [PATCH 7/7] feat(examples): live view of the desktop, and a handOff
 tool to take over

noVNC shows the sandbox desktop next to the chat. When the model is
stuck it calls handOff, the run stops, and the user drives the desktop
until they click Done.
---
 docs/config.json                              |   3 +-
 docs/tutorials/computer-use-login.md          | 103 +++++++++++++-
 examples/react/computer-use-login/README.md   |  28 +++-
 .../computer-use-login/sandbox/Dockerfile     |   4 +-
 .../computer-use-login/sandbox/desktop.sh     |  10 +-
 .../react/computer-use-login/src/hand-off.ts  |  17 +++
 .../react/computer-use-login/src/harness.ts   |  50 ++++++-
 .../computer-use-login/src/routeTree.gen.ts   |  24 +++-
 .../computer-use-login/src/routes/api.live.ts |  18 +++
 .../computer-use-login/src/routes/index.tsx   | 128 +++++++++++++++++-
 10 files changed, 362 insertions(+), 23 deletions(-)
 create mode 100644 examples/react/computer-use-login/src/hand-off.ts
 create mode 100644 examples/react/computer-use-login/src/routes/api.live.ts

diff --git a/docs/config.json b/docs/config.json
index ad5c530a82..546667e9f7 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -103,7 +103,8 @@
         {
           "label": "Sign In Without the Model",
           "to": "tutorials/computer-use-login",
-          "addedAt": "2026-11-03"
+          "addedAt": "2026-11-03",
+          "updatedAt": "2026-11-04"
         },
         {
           "label": "Subscribe to MCP Events",
diff --git a/docs/tutorials/computer-use-login.md b/docs/tutorials/computer-use-login.md
index 0d866f7126..95179b2a57 100644
--- a/docs/tutorials/computer-use-login.md
+++ b/docs/tutorials/computer-use-login.md
@@ -105,7 +105,7 @@ done
 
 - `--user-data-dir` keeps the cookies. A restarted container is still signed in.
 - `--password-store=basic` uses the same cookie key in every container. A profile that a new container restores can read its cookies.
-- `--remote-debugging-port` listens on 127.0.0.1 inside the container only. No port leaves the container.
+- `--remote-debugging-port` listens on 127.0.0.1 inside the container only. That port never leaves the container.
 
 `sandbox/browser.sh` stops and starts Chromium, so a snapshot saves a complete profile. Copy it from the [example](https://github.com/TanStack/ai/blob/main/examples/react/computer-use-login/sandbox/browser.sh):
 
@@ -549,4 +549,105 @@ When you are signed in, say what the page shows and stop.
 
 The model opens the practice page and calls `requestLogin`. Type `tomsmith` and `SuperSecretPassword!` in the card, then click Sign in. The model says that the page shows the Secure Area. Your password is not in the chat, the tool result, or the harness log.
 
+## 8. Watch the desktop and take over
+
+Show the desktop live next to the chat. When the model is stuck, it calls a `handOff` tool, and the user uses the desktop until they click Done.
+
+1. Add the live view to `sandbox/Dockerfile`. Put `x11vnc novnc python3-websockify` after `ca-certificates` in the `apt-get install` line.
+
+2. Start it in `sandbox/desktop.sh`, after the `until` line. Each start makes a new VNC password:
+
+   ```bash
+   head -c 64 /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 8 > /tmp/vnc-password
+   x11vnc -display :0 -localhost -forever -shared -quiet \
+     -passwdfile /tmp/vnc-password -rfbport 5900 &
+   websockify --web /usr/share/novnc 6080 localhost:5900 >/dev/null 2>&1 &
+   ```
+
+3. Build the image again, then publish the noVNC port in `src/harness.ts`. Docker publishes it on 127.0.0.1 only:
+
+   ```typescript ignore
+   const provider = dockerSandbox({
+     image: 'computer-use-login-desktop',
+     keepAliveCommand: ['/opt/desktop/desktop.sh'],
+     publishPorts: [6080],
+   })
+   ```
+
+4. Add a function to `src/harness.ts` that gives the address of the live view, with its password:
+
+   ```typescript ignore
+   export async function liveViewUrl(threadId: string) {
+     const id = await sandboxIds.get(threadId)
+     const sandbox = id === undefined ? null : await provider.resume({ id })
+     if (!sandbox) return null
+     const [{ url }, password] = await Promise.all([
+       sandbox.ports.connect(6080),
+       sandbox.process.exec('cat /tmp/vnc-password'),
+     ])
+     if (password.exitCode !== 0) {
+       throw new Error(`No live view password: ${password.stderr.trim()}`)
+     }
+     const params = new URLSearchParams({
+       autoconnect: '1',
+       reconnect: '1',
+       resize: 'scale',
+       password: password.stdout.trim(),
+     })
+     return `${url}/vnc.html?${params}`
+   }
+   ```
+
+   Return it from a `GET /api/live?threadId=...` route as `{ url }`. Copy [`api.live.ts`](https://github.com/TanStack/ai/blob/main/examples/react/computer-use-login/src/routes/api.live.ts) from the example.
+
+5. Create `src/hand-off.ts`. The tool has `needsApproval: true`, so the run stops until the user clicks Done:
+
+   ```typescript
+   import { toolDefinition } from '@tanstack/ai'
+   import { z } from 'zod'
+
+   export const handOffTool = toolDefinition({
+     name: 'handOff',
+     description:
+       'Give the desktop to the user, and wait until the user is done. Call it when you are stuck and cannot continue alone: a captcha, a two-factor code, a page that you cannot use, or a choice that only the user can make. Then take a screenshot to see what the user did.',
+     needsApproval: true,
+     inputSchema: z.object({
+       reason: z
+         .string()
+         .describe('What the user must do, in one sentence. The user reads it.'),
+     }),
+   })
+   ```
+
+6. Give the server tool to the harness in `src/harness.ts`:
+
+   ```typescript ignore
+   const handOff = handOffTool.server(
+     () => 'The user is done. Take a screenshot to see the screen.',
+   )
+
+   // In defineHarness:
+   tools: [requestLogin, handOff],
+   ```
+
+7. In `src/routes/index.tsx`, add `handOffTool.client()` to the `tools` of `useChat`. Then show the live view in an `<iframe>`. Add `&view_only=1` to its address, except while a `handOff` approval waits:
+
+   ```tsx ignore
+   const handedOff = interrupts.some(
+     (interrupt) =>
+       interrupt.kind === 'tool-approval' && interrupt.toolName === 'handOff',
+   )
+
+   <iframe
+     src={handedOff ? url : `${url}&view_only=1`}
+     title="Live view of the desktop"
+   />
+   ```
+
+   For the `handOff` approval, show `interrupt.originalArgs.reason` with a Done button that calls `interrupt.resolveInterrupt(true)`. Copy the `LiveView` and `HandOffCard` components from the [example](https://github.com/TanStack/ai/blob/main/examples/react/computer-use-login/src/routes/index.tsx).
+
+Start the app, and send a task that needs a person, for example "Open https://www.google.com/recaptcha/api2/demo and send the form." The model calls `handOff`. Tick the captcha in the live view, then click Done. The model continues.
+
+The model sees only the screenshots that it takes after you click Done. If the user types a password in the live view, the model sees only dots.
+
 The full example is on GitHub: [TanStack/ai `examples/react/computer-use-login`](https://github.com/TanStack/ai/tree/main/examples/react/computer-use-login). To host it, see [Run it on a server](https://github.com/TanStack/ai/tree/main/examples/react/computer-use-login#run-it-on-a-server) in its README.
diff --git a/examples/react/computer-use-login/README.md b/examples/react/computer-use-login/README.md
index 4e81988fc8..32d25d1da3 100644
--- a/examples/react/computer-use-login/README.md
+++ b/examples/react/computer-use-login/README.md
@@ -2,7 +2,9 @@
 
 Your agent uses a desktop, and a site asks it for a password. In this app, the model calls `requestLogin`. You type the username and password in a card in the chat. The server fills the form in the browser, and the model never sees the password.
 
-The desktop is a Docker container with Chromium on it. Each chat thread keeps its own container, so it stays signed in when you come back later. The app also saves the Chromium profile after each sign-in. When the container of a thread is gone, a new container gets the profile back, still signed in.
+The desktop is a Docker container with Chromium on it. The page shows it live, next to the chat. When the model is stuck, it calls `handOff`, and you use the desktop yourself.
+
+Each chat thread keeps its own container, so it stays signed in when you come back later. The app also saves the Chromium profile after each sign-in. When the container of a thread is gone, a new container gets the profile back, still signed in.
 
 ## Run it
 
@@ -25,15 +27,28 @@ The model opens a practice sign-in page. When the login card shows, type `tomsmi
 6. The tool saves a snapshot of the Chromium profile, with the cookies of the sign-in.
 7. The model gets "Signed in" and the address of the page.
 
-The model sees the screen, so Chromium must never show a password. `sandbox/policy.json` turns off the password manager and `javascript:` URLs. Chromium listens for its debugging protocol only inside the container. No port leaves it.
+The model sees the screen, so Chromium must never show a password. `sandbox/policy.json` turns off the password manager and `javascript:` URLs. Chromium listens for its debugging protocol only inside the container. That port never leaves it.
+
+## Take over the desktop
+
+The live view is noVNC, a VNC viewer in the browser. It is view-only while the model works.
+
+1. The model calls `handOff({ reason })`, for example for a captcha or a two-factor code. The tool has `needsApproval: true`, so the run stops.
+2. A card shows the reason. The live view now takes your mouse and keyboard.
+3. Do the step on the desktop, then click Done. The model takes a screenshot and continues. Click Cancel to tell the model that you did not do it.
+
+The model sees only the screenshots that it takes after you click Done. If you type a password in the live view, the model sees only dots. The login card is still the better path for a password, because the server checks the origin of the page before it fills the form.
+
+The live view needs a password. The container makes a new one at each start, and `/api/live` reads it. Docker publishes the noVNC port on 127.0.0.1 only, so other computers on your network cannot connect.
 
 ## Files
 
 - `src/harness.ts`: the harness, the Docker provider, the `requestLogin` tool, and the three stores.
-- `src/request-login.ts`: the tool definition that the server and the browser share.
+- `src/request-login.ts` and `src/hand-off.ts`: the tool definitions that the server and the browser share.
 - `src/routes/api.login.ts`: the route that takes the username and password.
-- `src/routes/index.tsx`: the chat and the login card.
-- `sandbox/`: the desktop image. `desktop.sh` starts the screen and Chromium. `browser.sh` stops and starts Chromium for a snapshot. `login.py` fills the form.
+- `src/routes/api.live.ts`: the route that gives the address of the live view.
+- `src/routes/index.tsx`: the chat, the cards, and the live view.
+- `sandbox/`: the desktop image. `desktop.sh` starts the screen, the live view, and Chromium. `browser.sh` stops and starts Chromium for a snapshot. `login.py` fills the form.
 
 ## Run it on a server
 
@@ -60,7 +75,6 @@ A provider whose disk does not last, like Cloudflare, also keeps the sign-in. Ea
 
 ## Not in this app
 
-- Two-factor codes.
-- A live view of the desktop for a captcha.
+- A live view on a hosted provider. E2B Desktop has its own stream that you can use instead of noVNC.
 
 CAUTION: The harness route has no login, and the browser can open every address that your server can reach. Run this app only on your own machine.
diff --git a/examples/react/computer-use-login/sandbox/Dockerfile b/examples/react/computer-use-login/sandbox/Dockerfile
index 74a4c2b821..8cd39d6a53 100644
--- a/examples/react/computer-use-login/sandbox/Dockerfile
+++ b/examples/react/computer-use-login/sandbox/Dockerfile
@@ -1,5 +1,5 @@
 # The desktop that the model uses: a screen, the tools of the sandbox
-# computer driver, Chromium, and the sign-in script.
+# computer driver, Chromium, the sign-in script, and a live view (noVNC).
 # Build it from the example folder: docker build -t computer-use-login-desktop sandbox
 FROM debian:bookworm-slim
 
@@ -7,7 +7,7 @@ RUN printf 'Acquire::Retries "10";\nAcquire::ForceIPv4 "true";\n' > /etc/apt/apt
   && apt-get update \
   && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
     xvfb xdotool scrot x11-utils chromium fonts-dejavu-core \
-    python3 python3-websockets ca-certificates \
+    python3 python3-websockets ca-certificates x11vnc novnc python3-websockify \
   && rm -rf /var/lib/apt/lists/*
 
 # The model sees the screen and moves the mouse. So Chromium must never show
diff --git a/examples/react/computer-use-login/sandbox/desktop.sh b/examples/react/computer-use-login/sandbox/desktop.sh
index 9d973ab2ff..776d183191 100644
--- a/examples/react/computer-use-login/sandbox/desktop.sh
+++ b/examples/react/computer-use-login/sandbox/desktop.sh
@@ -3,11 +3,19 @@
 # Chromium closes, it starts again. The profile folder keeps the cookies, so a
 # restarted container is still signed in.
 # Chromium listens for the debugging protocol on 127.0.0.1 inside the
-# container only. The sign-in script uses it. No port leaves the container.
+# container only. The sign-in script uses it. That port never leaves the container.
 rm -f /tmp/.X0-lock
 Xvfb :0 -ac -screen 0 1024x768x24 -nolisten tcp &
 until DISPLAY=:0 xdpyinfo >/dev/null 2>&1; do sleep 0.2; done
 
+# The live view. x11vnc shares the screen on port 5900 inside the container,
+# with a new password at each start. websockify serves noVNC on port 6080,
+# which the app publishes on 127.0.0.1 only. The server reads the password.
+head -c 64 /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 8 > /tmp/vnc-password
+x11vnc -display :0 -localhost -forever -shared -quiet \
+  -passwdfile /tmp/vnc-password -rfbport 5900 &
+websockify --web /usr/share/novnc 6080 localhost:5900 >/dev/null 2>&1 &
+
 while true; do
   # browser.sh stop pauses this loop while a snapshot saves or restores the profile.
   # With no address, Chromium opens the tabs of its last session (RestoreOnStartup).
diff --git a/examples/react/computer-use-login/src/hand-off.ts b/examples/react/computer-use-login/src/hand-off.ts
new file mode 100644
index 0000000000..86eacf9cb7
--- /dev/null
+++ b/examples/react/computer-use-login/src/hand-off.ts
@@ -0,0 +1,17 @@
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+// The server and the browser both import this definition, like requestLogin.
+export const handOffTool = toolDefinition({
+  name: 'handOff',
+  description:
+    'Give the desktop to the user, and wait until the user is done. Call it when you are stuck and cannot continue alone: a captcha, a two-factor code, a page that you cannot use, or a choice that only the user can make. Then take a screenshot to see what the user did.',
+  // The run stops. The live view lets the user use the desktop until they
+  // click Done, which approves the call.
+  needsApproval: true,
+  inputSchema: z.object({
+    reason: z
+      .string()
+      .describe('What the user must do, in one sentence. The user reads it.'),
+  }),
+})
diff --git a/examples/react/computer-use-login/src/harness.ts b/examples/react/computer-use-login/src/harness.ts
index ba41244595..e307765d93 100644
--- a/examples/react/computer-use-login/src/harness.ts
+++ b/examples/react/computer-use-login/src/harness.ts
@@ -14,13 +14,17 @@ import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
 import { openaiText } from '@tanstack/ai-openai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import { z } from 'zod'
+import { handOffTool } from './hand-off'
 import { requestLoginTool } from './request-login'
 
 // One Docker container for each chat thread. The image comes from
-// `sandbox/Dockerfile`. Its main process starts the screen and Chromium.
+// `sandbox/Dockerfile`. Its main process starts the screen, Chromium, and the
+// live view (noVNC on port 6080).
+const LIVE_VIEW_PORT = 6080
 const provider = dockerSandbox({
   image: 'computer-use-login-desktop',
   keepAliveCommand: ['/opt/desktop/desktop.sh'],
+  publishPorts: [LIVE_VIEW_PORT],
 })
 
 // The container id of each thread, in a file. A thread keeps its container,
@@ -59,6 +63,36 @@ const sandboxIds = {
   },
 }
 
+/**
+ * The container of a thread, or null before the model's first action. The
+ * container can be stopped, for example when the user answers a card hours
+ * later. `resume` starts it again.
+ */
+async function threadSandbox(threadId: string) {
+  const id = await sandboxIds.get(threadId)
+  return id === undefined ? null : provider.resume({ id })
+}
+
+/** The noVNC address of a thread's desktop, or null when it has none yet. */
+export async function liveViewUrl(threadId: string) {
+  const sandbox = await threadSandbox(threadId)
+  if (!sandbox) return null
+  const [{ url }, password] = await Promise.all([
+    sandbox.ports.connect(LIVE_VIEW_PORT),
+    sandbox.process.exec('cat /tmp/vnc-password'),
+  ])
+  if (password.exitCode !== 0) {
+    throw new Error(`No live view password: ${password.stderr.trim()}`)
+  }
+  const params = new URLSearchParams({
+    autoconnect: '1',
+    reconnect: '1',
+    resize: 'scale',
+    password: password.stdout.trim(),
+  })
+  return `${url}/vnc.html?${params}`
+}
+
 // The Chromium profile of each thread, saved after a sign-in and when the
 // thread goes idle. A thread whose container is gone gets a new container
 // with this profile, so it is still signed in.
@@ -157,10 +191,7 @@ const requestLogin = requestLoginTool.server(async ({ site }, context) => {
   if (!threadId) throw new Error('requestLogin runs only in a chat thread.')
   const login = takeLogin(threadId, site)
 
-  // The user can answer the card hours later. The container of the thread
-  // can be stopped by then. `resume` starts it again.
-  const id = await sandboxIds.get(threadId)
-  const sandbox = id === undefined ? null : await provider.resume({ id })
+  const sandbox = await threadSandbox(threadId)
   if (!sandbox) {
     throw new Error(
       'This thread has no computer. Take a screenshot, then call requestLogin again.',
@@ -188,6 +219,12 @@ const requestLogin = requestLoginTool.server(async ({ site }, context) => {
   return `Signed in. The browser shows ${page.url}. Take a screenshot to see it.`
 })
 
+// The model is stuck. The user used the desktop in the live view and clicked
+// Done. A click on Cancel declines the call, and the model gets told so.
+const handOff = handOffTool.server(
+  () => 'The user is done. Take a screenshot to see the screen.',
+)
+
 // One time, outside `plugins`, so every session shares the containers.
 const computer = computerUse({
   driver: sandboxComputer({ provider, sandboxIds, snapshots }),
@@ -200,8 +237,9 @@ const agent = defineHarness({
   adapter: openaiText('gpt-6.1-sol'),
   systemPrompts: [
     'You use a Linux desktop with Chromium on it. When a page asks you to sign in, call requestLogin with the address of the sign-in page. Never ask for a password in the chat, and never type one.',
+    'When you are stuck and cannot continue alone, call handOff. The user then uses the desktop and tells you when they are done.',
   ],
-  tools: [requestLogin],
+  tools: [requestLogin, handOff],
   plugins: () => [permissions(), computer],
 })
 
diff --git a/examples/react/computer-use-login/src/routeTree.gen.ts b/examples/react/computer-use-login/src/routeTree.gen.ts
index f093a916e8..5b9906b538 100644
--- a/examples/react/computer-use-login/src/routeTree.gen.ts
+++ b/examples/react/computer-use-login/src/routeTree.gen.ts
@@ -10,6 +10,7 @@
 
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as IndexRouteImport } from './routes/index'
+import { Route as ApiLiveRouteImport } from './routes/api.live'
 import { Route as ApiLoginRouteImport } from './routes/api.login'
 import { Route as ApiHarnessSplatRouteImport } from './routes/api.harness.$'
 
@@ -18,6 +19,11 @@ const IndexRoute = IndexRouteImport.update({
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiLiveRoute = ApiLiveRouteImport.update({
+  id: '/api/live',
+  path: '/api/live',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiLoginRoute = ApiLoginRouteImport.update({
   id: '/api/login',
   path: '/api/login',
@@ -31,30 +37,34 @@ const ApiHarnessSplatRoute = ApiHarnessSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/api/live': typeof ApiLiveRoute
   '/api/login': typeof ApiLoginRoute
   '/api/harness/$': typeof ApiHarnessSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/api/live': typeof ApiLiveRoute
   '/api/login': typeof ApiLoginRoute
   '/api/harness/$': typeof ApiHarnessSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/api/live': typeof ApiLiveRoute
   '/api/login': typeof ApiLoginRoute
   '/api/harness/$': typeof ApiHarnessSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/api/login' | '/api/harness/$'
+  fullPaths: '/' | '/api/live' | '/api/login' | '/api/harness/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/api/login' | '/api/harness/$'
-  id: '__root__' | '/' | '/api/login' | '/api/harness/$'
+  to: '/' | '/api/live' | '/api/login' | '/api/harness/$'
+  id: '__root__' | '/' | '/api/live' | '/api/login' | '/api/harness/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  ApiLiveRoute: typeof ApiLiveRoute
   ApiLoginRoute: typeof ApiLoginRoute
   ApiHarnessSplatRoute: typeof ApiHarnessSplatRoute
 }
@@ -68,6 +78,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/live': {
+      id: '/api/live'
+      path: '/api/live'
+      fullPath: '/api/live'
+      preLoaderRoute: typeof ApiLiveRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/login': {
       id: '/api/login'
       path: '/api/login'
@@ -87,6 +104,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  ApiLiveRoute: ApiLiveRoute,
   ApiLoginRoute: ApiLoginRoute,
   ApiHarnessSplatRoute: ApiHarnessSplatRoute,
 }
diff --git a/examples/react/computer-use-login/src/routes/api.live.ts b/examples/react/computer-use-login/src/routes/api.live.ts
new file mode 100644
index 0000000000..646e23c659
--- /dev/null
+++ b/examples/react/computer-use-login/src/routes/api.live.ts
@@ -0,0 +1,18 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { liveViewUrl } from '@/harness'
+
+// The address of the live view of a thread's desktop. It holds the VNC
+// password, so only this machine can reach it (see `publishPorts`).
+export const Route = createFileRoute('/api/live')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const threadId = new URL(request.url).searchParams.get('threadId')
+        if (!threadId) {
+          return Response.json({ error: 'Send a thread id.' }, { status: 400 })
+        }
+        return Response.json({ url: await liveViewUrl(threadId) })
+      },
+    },
+  },
+})
diff --git a/examples/react/computer-use-login/src/routes/index.tsx b/examples/react/computer-use-login/src/routes/index.tsx
index 9d443a52f2..caf2441a54 100644
--- a/examples/react/computer-use-login/src/routes/index.tsx
+++ b/examples/react/computer-use-login/src/routes/index.tsx
@@ -1,6 +1,8 @@
 import { useEffect, useRef, useState } from 'react'
 import { createFileRoute } from '@tanstack/react-router'
 import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { z } from 'zod'
+import { handOffTool } from '@/hand-off'
 import { requestLoginTool } from '@/request-login'
 import type { UIMessage } from '@tanstack/ai-react'
 
@@ -189,6 +191,110 @@ function LoginCard({
   )
 }
 
+/**
+ * The model is stuck and gave the desktop to the user. The live view takes
+ * the mouse and keyboard until the user clicks Done.
+ */
+function HandOffCard({
+  reason,
+  onAnswer,
+}: {
+  reason: string
+  onAnswer: (done: boolean) => void
+}) {
+  return (
+    <div className="mx-4 mt-2 rounded-lg border border-sky-500/30 bg-sky-500/10 p-3 text-sm text-sky-100">
+      <p className="font-medium">The model needs you</p>
+      <p className="mb-2">{reason}</p>
+      <p className="mb-2 text-xs text-sky-200/80">
+        Use the desktop in the live view. Then click Done, and the model
+        continues.
+      </p>
+      <div className="flex gap-2">
+        <button
+          type="button"
+          onClick={() => onAnswer(true)}
+          className="rounded bg-sky-600 px-3 py-1 text-white"
+        >
+          Done
+        </button>
+        <button
+          type="button"
+          onClick={() => onAnswer(false)}
+          className="rounded bg-gray-700 px-3 py-1 text-white"
+        >
+          Cancel
+        </button>
+      </div>
+    </div>
+  )
+}
+
+const liveViewSchema = z.object({ url: z.string().nullable() })
+
+/**
+ * The thread's desktop in real time, through noVNC. It is view-only, except
+ * while the model hands the desktop to the user.
+ */
+function LiveView({ interactive }: { interactive: boolean }) {
+  const [url, setUrl] = useState<string | null>(null)
+  const [error, setError] = useState<string>()
+
+  // The container starts at the model's first action. Ask until it exists.
+  // ponytail: a restarted container has a new VNC password. Reload the page.
+  useEffect(() => {
+    if (url) return
+    const load = async () => {
+      try {
+        const response = await fetch(
+          `/api/live?${new URLSearchParams({ threadId: THREAD_ID })}`,
+        )
+        if (!response.ok) {
+          throw new Error(`No live view (${response.status}).`)
+        }
+        setUrl(liveViewSchema.parse(await response.json()).url)
+        setError(undefined)
+      } catch (loadError) {
+        setError(
+          loadError instanceof Error ? loadError.message : String(loadError),
+        )
+      }
+    }
+    void load()
+    const timer = setInterval(load, 2000)
+    return () => clearInterval(timer)
+  }, [url])
+
+  return (
+    <div className="flex w-1/2 flex-col gap-2 border-l border-orange-500/10 p-4">
+      <p className="text-sm text-gray-400">
+        {interactive
+          ? 'You have the desktop. Click Done in the chat when you finish.'
+          : 'Live view. The model has the desktop.'}
+      </p>
+      <div
+        className={`aspect-4/3 w-full overflow-hidden rounded border ${
+          interactive
+            ? 'border-sky-500 ring-2 ring-sky-500/50'
+            : 'border-gray-700'
+        }`}
+      >
+        {url ? (
+          <iframe
+            src={interactive ? url : `${url}&view_only=1`}
+            title="Live view of the desktop"
+            className="h-full w-full"
+          />
+        ) : (
+          <div className="flex h-full items-center justify-center text-sm text-gray-500">
+            {error ?? 'The desktop starts at the first action of the model.'}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
 /** Another approval, like an OpenAI safety check on a computer action. */
 function ApprovalCard({
   message,
@@ -228,7 +334,7 @@ function ChatPage() {
       threadId: THREAD_ID,
       // No browser code: the tool runs on the server. This gives the
       // approval of the tool its typed arguments.
-      tools: [requestLoginTool.client()],
+      tools: [requestLoginTool.client(), handOffTool.client()],
       // Load the thread from the server after a reload.
       persistence: true,
     },
@@ -240,12 +346,29 @@ function ChatPage() {
     setInput('')
   }
 
+  const handedOff = interrupts.some(
+    (interrupt) =>
+      interrupt.kind === 'tool-approval' && interrupt.toolName === 'handOff',
+  )
+
   return (
     <div className="flex h-screen bg-gray-900">
-      <div className="flex w-full flex-col">
+      <div className="flex w-1/2 flex-col">
         <Messages messages={messages} />
 
         {interrupts.map((interrupt) => {
+          if (
+            interrupt.kind === 'tool-approval' &&
+            interrupt.toolName === 'handOff'
+          ) {
+            return (
+              <HandOffCard
+                key={interrupt.id}
+                reason={interrupt.originalArgs.reason}
+                onAnswer={(done) => interrupt.resolveInterrupt(done)}
+              />
+            )
+          }
           if (interrupt.kind === 'tool-approval') {
             return (
               <LoginCard
@@ -307,6 +430,7 @@ function ChatPage() {
           </div>
         </div>
       </div>
+      <LiveView interactive={handedOff} />
     </div>
   )
 }