fix(ai-sandbox-docker): close sbx review bugs A46-A54

Allow localhost on real sbx allowlists so the host proxy rewrite
does not block the tool bridge. Keep denyNetwork-only empty.

Treat more already-exists texts as a live name collision. Delete
the owned clone on that path. Do not run sbx rm.

Walk every brace in parseJsonAfterBanner. Do not treat a sandbox
already-exists as policy init success.

Fix the connectPort error after a live publish. Add the abort
listener before reading aborted. Drop the stale Task 8 comments.

Author: AlemTuzlak

docs/config.json

@@ -498,7 +498,7 @@
           "label": "Overview",
           "to": "sandbox/overview",
           "addedAt": "2026-06-16",
-          "updatedAt": "2026-08-11"
+          "updatedAt": "2026-08-12"
         },
         {
           "label": "Quick Start",
@@ -528,7 +528,7 @@
           "label": "Tools",
           "to": "sandbox/tools",
           "addedAt": "2026-06-29",
-          "updatedAt": "2026-08-04"
+          "updatedAt": "2026-08-12"
         },
         {
           "label": "Policy",

docs/sandbox/overview.md

@@ -108,8 +108,8 @@ shell.
 [Quick Start](./quick-start) gets an agent fixing a bug in a sandbox on your laptop.
 After that, pick the piece you need:
 
-- [Providers](./providers): local process, Docker, Daytona, Vercel, Sprites, and what
-  each one can do.
+- [Providers](./providers): local process, Docker container, Docker Sandboxes
+  (`sbxSandbox`), Daytona, Vercel, Sprites, and what each one can do.
 - [Harnesses](./harnesses): which agent runs. Grok Build, Claude Code, Codex,
   OpenCode, or any ACP agent.
 - [Workspace](./workspace): the source repo, clone depth, and setup commands.

docs/sandbox/policy.md

@@ -99,10 +99,11 @@ Most providers leave `capabilities.network` to the harness. `sbxSandbox()` also
 
 | TanStack `capabilities.network` | What `sbxSandbox()` writes |
 | --- | --- |
-| No policy and no `allowNetwork` / `denyNetwork` | If the policy list is empty, `sbxSandbox()` runs `sbx policy init deny-all`. A known adapter (`grok-build`, `claude-code`, `codex`) then writes its model API host as a per-sandbox allow on top of that deny-all. Unknown adapters stay on the machine preset. |
-| No policy and `allowNetwork` | Per-sandbox allow of the model API host (when the adapter is known) plus `allowNetwork`, then apply `denyNetwork`. |
+| No policy and no `allowNetwork` / `denyNetwork` | If the policy list is empty, `sbxSandbox()` runs `sbx policy init deny-all`. A known adapter (`grok-build`, `claude-code`, `codex`) then writes its model API host and `localhost` as a per-sandbox allow on top of that deny-all. Unknown adapters stay on the machine preset. |
+| No policy and `allowNetwork` | Per-sandbox allow of the model API host (when the adapter is known), `localhost`, and `allowNetwork`, then apply `denyNetwork`. |
+| No policy and `denyNetwork` only | Per-sandbox deny of those hosts. Allow stays empty. No auto hosts and no `localhost`. This is additive deny on the machine preset. |
 | `allow` | Allow `**`, then apply `denyNetwork`. |
-| `deny` | Allow only the model API host plus `allowNetwork`, then apply `denyNetwork`. |
+| `deny` | Allow the model API host, `localhost`, and `allowNetwork`, then apply `denyNetwork`. |
 | `ask` (or the policy `default` when `network` is unset) | Same allowlist as `deny`. The harness still asks for tools and commands. |
 
 Auto-allowed model hosts:
@@ -114,6 +115,8 @@ Auto-allowed model hosts:
 
 If the allowlist would be empty under `deny` or `ask`, create throws. Pass `allowNetwork`, or use `grokBuildText` / `claudeCodeText` / `codexText`.
 
+The guest still dials `host.docker.internal` for the tool bridge. The `sbx` proxy rewrites that host to `localhost` before the policy match. `sbxSandbox()` adds `localhost` when it writes a real allowlist. It does not add `localhost` for `denyNetwork` only.
+
 ```ts
 import { sbxSandbox } from '@tanstack/ai-sandbox-docker'
 import { defineSandbox, defineSandboxPolicy } from '@tanstack/ai-sandbox'

docs/sandbox/quick-start.md

@@ -194,12 +194,12 @@ export const repoSandbox = defineSandbox({
 ## Run the working example
 
 A complete, runnable app ships at
-[`examples/sandbox-web`](https://github.com/TanStack/ai/tree/main/examples/sandbox-web)
-a "build me an app" agent (Claude Code on a Docker sandbox) with durable,
-refresh-surviving runs; it scaffolds an app in the sandbox, runs the dev
-server, and streams back a live preview URL. For a coding agent running at the
-edge, with the harness (Claude Code, Codex, Grok Build) picked per run from
-the UI, see
+[`examples/sandbox-web`](https://github.com/TanStack/ai/tree/main/examples/sandbox-web).
+That app is a "build me an app" agent (Claude Code on a Docker sandbox) with
+durable, refresh-surviving runs. It scaffolds an app in the sandbox, runs the
+dev server, and streams back a live preview URL. For a coding agent running at
+the edge, with the harness (Claude Code, Codex, Grok Build) picked per run
+from the UI, see
 [`examples/sandbox-cloudflare`](https://github.com/TanStack/ai/tree/main/examples/sandbox-cloudflare).
 
 From here:

docs/sandbox/tools.md

@@ -68,15 +68,24 @@ That holds in two cases and breaks in a third.
 
 | Topology | Host the sandbox dials | Setup |
 | --- | --- | --- |
-| Local process / Docker | `localhost` / `host.docker.internal` | None. Works out of the box. |
-| Deployed orchestrator (production) | Your public host, derived from the request | None. Works out of the box. |
+| Local process | `localhost` | None. Works by default. |
+| Docker container (`dockerSandbox`) | `host.docker.internal` | None. Works by default. |
+| Docker Sandboxes (`sbxSandbox`) | `host.docker.internal` | The guest URL stays `host.docker.internal`. The `sbx` proxy rewrites that host to `localhost` before the policy match. A deny or ask allowlist must include `localhost`. `sbxSandbox()` adds `localhost` when it writes a real allowlist. |
+| Deployed orchestrator (production) | Your public host, derived from the request | None. Works by default. |
 | Remote cloud sandbox, driven from your laptop | Your laptop, which has no public URL | Tunnel the bridge with `withNgrokBridge`. |
 
-### Local process / Docker
+### Local process / Docker container
 
 The orchestrator is the same machine as the sandbox, reached on `localhost`
-(local-process) or `host.docker.internal` (Docker). Bridged tools work with no
-extra configuration.
+(local-process) or `host.docker.internal` (Docker container). Bridged tools
+work with no extra configuration.
+
+### Docker Sandboxes (`sbxSandbox`)
+
+The guest still dials `host.docker.internal`. The host HTTP proxy rewrites
+that host to `localhost` before it checks `sbx policy`. If you write a deny
+or ask allowlist, allow `localhost` (or let `sbxSandbox()` add it).
+`denyNetwork` alone does not write that allowlist.
 
 ### A deployed orchestrator (production)
 

packages/ai-sandbox-docker/README.md

@@ -9,7 +9,12 @@ Sandbox providers that run a TanStack AI harness on Docker.
 import { dockerSandbox, sbxSandbox } from '@tanstack/ai-sandbox-docker'
 
 const container = dockerSandbox({ image: 'node:22' })
-const microvm = sbxSandbox()
+const microvm = sbxSandbox({
+  allowNetwork: ['*.npmjs.org', 'registry.npmjs.org'],
+})
 ```
 
-`sbxSandbox()` needs `sbx` on `PATH`, `sbx login`, a hypervisor, and a Git repo to pass to `sbx create --clone`. See the [providers guide](https://tanstack.com/ai/latest/docs/sandbox/providers).
+`sbxSandbox()` needs `sbx` on `PATH`, `sbx login`, a hypervisor, and a Git
+repo to pass to `sbx create --clone`. Pass `allowNetwork` when you use a
+deny or ask policy, or when you need extra hosts besides the model API host
+and `localhost`. See the [providers guide](https://tanstack.com/ai/latest/docs/sandbox/providers).

packages/ai-sandbox-docker/src/sbx/cli.ts

@@ -70,8 +70,8 @@ export function defaultSpawn(
     })
   })
   if (opts.signal) {
+    opts.signal.addEventListener('abort', onAbort, { once: true })
     if (opts.signal.aborted) child.kill()
-    else opts.signal.addEventListener('abort', onAbort, { once: true })
   }
   return {
     kill: () => {
@@ -255,22 +255,23 @@ export function sbxExecArgs(
  * Walk every `{` / `[` until one slice parses.
  */
 export function parseJsonAfterBanner(stdout: string): unknown {
-  const brace = stdout.indexOf('{')
-  const bracket = stdout.indexOf('[')
-  const starts = [brace, bracket].filter((i) => i >= 0).sort((a, b) => a - b)
-  if (starts.length === 0) {
-    throw new SyntaxError(
-      `sbx JSON: no object or array in: ${stdout.slice(0, 200)}`,
-    )
-  }
   let lastError: unknown
-  for (const start of starts) {
+  let sawStart = false
+  for (let i = 0; i < stdout.length; i++) {
+    const ch = stdout[i]
+    if (ch !== '{' && ch !== '[') continue
+    sawStart = true
     try {
-      return JSON.parse(stdout.slice(start)) as unknown
+      return JSON.parse(stdout.slice(i)) as unknown
     } catch (error) {
       lastError = error
     }
   }
+  if (!sawStart) {
+    throw new SyntaxError(
+      `sbx JSON: no object or array in: ${stdout.slice(0, 200)}`,
+    )
+  }
   throw lastError instanceof Error
     ? lastError
     : new SyntaxError(`sbx JSON: ${stdout.slice(0, 200)}`)

packages/ai-sandbox-docker/src/sbx/handle.ts

@@ -4,8 +4,8 @@
  * fs is the same base64-over-exec design as the container handle. Kill uses
  * the same in-VM pid file. Do not only kill the host `sbx exec` process.
  *
- * `writableStdin` and `killableProcesses` stay false until the live test in
- * Task 8 measures them.
+ * `writableStdin` and `killableProcesses` stay false until a live
+ * measurement after `sbx login`.
  */
 import { randomUUID } from 'node:crypto'
 import { createExecBackedGit } from '@tanstack/ai-sandbox'
@@ -32,9 +32,9 @@ export const SBX_CAPS: SandboxCapabilities = {
   env: true,
   ports: true,
   backgroundProcesses: true,
-  // Stay false until the live test in Task 8 proves stdin works.
+  // Stay false until a live measurement after `sbx login` proves stdin works.
   writableStdin: false,
-  // Stay false until the live test in Task 8 proves in-VM kill works.
+  // Stay false until a live measurement after `sbx login` proves in-VM kill.
   killableProcesses: false,
   snapshots: false,
   networkPolicy: true,
@@ -171,9 +171,7 @@ export function isAlreadyGone(error: unknown): boolean {
 
 export function isNameAlreadyExists(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error)
-  return /(?:sandbox|vm|container)\s+(?:'[^']+'|"[^"]+"|\S+)\s+already exists/i.test(
-    message,
-  )
+  return /(?:sandbox|vm|container).{0,80}already exists/i.test(message)
 }
 
 /** Host login or transport text that `test -e` never prints for a missing path. */
@@ -549,7 +547,7 @@ export class SbxHandle implements SandboxHandle {
     const hostPort = hostPortFromPortsJson(listed.stdout, port)
     if (hostPort === null) {
       throw new Error(
-        `sbx: sandbox port ${port} is not published. Pass publishPorts: [${port}] to sbxSandbox() to reach it from the host.`,
+        `sbx: sandbox port ${port} is not in sbx ports --json after publish.`,
       )
     }
     return { url: `http://localhost:${hostPort}` }

packages/ai-sandbox-docker/src/sbx/policy.ts

@@ -13,12 +13,20 @@ const AUTO_HOSTS: Record<string, Array<string>> = {
 const EMPTY_ALLOWLIST =
   'sbxSandbox: network deny/ask has an empty allowlist. Pass allowNetwork, or use grokBuildText / claudeCodeText / codexText so the model API host is added.'
 
+/** Guest URLs use host.docker.internal; the sbx proxy rewrites that to localhost. */
+const BRIDGE_HOST = 'localhost'
+
 export function autoApiHosts(adapterName: string | undefined): Array<string> {
   if (!adapterName) return []
   if (!Object.hasOwn(AUTO_HOSTS, adapterName)) return []
   return AUTO_HOSTS[adapterName] ?? []
 }
 
+function withBridgeHost(hosts: Array<string>): Array<string> {
+  if (hosts.includes(BRIDGE_HOST) || hosts.includes('**')) return hosts
+  return [...hosts, BRIDGE_HOST]
+}
+
 function networkDecision(
   policy: SandboxPolicy | undefined,
 ): PolicyDecision | undefined {
@@ -38,7 +46,7 @@ export function planSbxPolicy(input: {
   const auto = autoApiHosts(input.adapterName)
   if (!input.policy && !hasHostLists) {
     if (auto.length > 0) {
-      return { kind: 'per-sandbox', allow: auto, deny: [] }
+      return { kind: 'per-sandbox', allow: withBridgeHost(auto), deny: [] }
     }
     return { kind: 'machine-preset' }
   }
@@ -59,7 +67,14 @@ export function planSbxPolicy(input: {
   if (allow.length === 0 && (decision === 'deny' || decision === 'ask')) {
     throw new Error(EMPTY_ALLOWLIST)
   }
-  return { kind: 'per-sandbox', allow, deny }
+  // Real allowlists must include localhost. The proxy rewrites
+  // host.docker.internal to localhost before the policy match.
+  // denyNetwork-only keeps allow=[] (A19). Open ** stays ** only.
+  return {
+    kind: 'per-sandbox',
+    allow: mergeAuto && allow.length > 0 ? withBridgeHost(allow) : allow,
+    deny,
+  }
 }
 
 export function policyArgs(

packages/ai-sandbox-docker/src/sbx/provider.ts

@@ -111,9 +111,7 @@ function isAlreadyInitialized(error: unknown): boolean {
     error instanceof Error ? error.message : String(error)
   ).toLowerCase()
   return (
-    message.includes('already initialized') ||
-    message.includes('already set') ||
-    message.includes('already exists')
+    message.includes('already initialized') || message.includes('already set')
   )
 }
 
@@ -247,16 +245,16 @@ class SbxProvider implements SandboxProvider {
       if (input.env) await handle.env.set(input.env)
       return handle
     } catch (error) {
+      if (host.owned) {
+        await removeOwnedClone(id)
+      }
       if (isNameAlreadyExists(error)) throw error
       let rmError: unknown
       try {
         await this.run(['rm', '--force', id])
       } catch (caught) {
         rmError = caught
       }
-      if (host.owned) {
-        await removeOwnedClone(id)
-      }
       if (rmError && !isAlreadyGone(rmError)) throw rmError
       throw error
     }