Optional Docker sandbox: whole-skvm-in-container via --sandbox

README.md

@@ -253,6 +253,70 @@ mkdir -p ~/.skvm/profiles
 cp -R skvm-data/profiles/. ~/.skvm/profiles/
 ```
 
+## Sandbox (Docker)
+
+Pass `--sandbox` to any skvm command to run the entire skvm process inside an
+ephemeral Docker container. Default behaviour is unchanged — without
+`--sandbox`, skvm runs on the host as before.
+
+```bash
+skvm run --sandbox --skill=./my-skill --task=./task.json
+skvm bench --sandbox --suite=...
+skvm jit-optimize --sandbox --skill=./foo --target-model=openrouter/...
+```
+
+### Image
+
+The launcher pulls
+`ghcr.io/sjtu-ipads/skvm-sandbox:<your-skvm-version>` from GitHub Container
+Registry. If the pull fails (offline, no auth, image not published yet for
+your version), build the image locally:
+
+```bash
+bun run build:binary
+docker build -f docker/skvm-sandbox.Dockerfile \
+  -t ghcr.io/sjtu-ipads/skvm-sandbox:$(bun run skvm --version) .
+```
+
+### Cleaning up leaked containers
+
+The launcher reaps containers automatically on the next invocation, but you
+can force-clean any time:
+
+```bash
+docker ps -a --filter label=skvm-sandbox=1 -q | xargs docker rm -f
+```
+
+### Mounts
+
+Three host paths are bind-mounted into the container:
+
+| Host | Inner | Mode |
+| --- | --- | --- |
+| `$(pwd)` | `/workspace` (container `WORKDIR`) | rw |
+| `$SKVM_CACHE` (default `~/.skvm`) | `/skvm-cache` | rw |
+| `$SKVM_DATA_DIR` (if set) | `/skvm-data` | ro |
+
+Path-shaped CLI flags whose values fall outside these roots get a dynamic
+per-flag mount under `/extra/`. The launcher rewrites the value to the
+inner path automatically.
+
+### Making sandbox the default
+
+Set `defaults.sandbox = true` in `~/.skvm/skvm.config.json` (or via
+`skvm config init`). With the default on, every command runs in sandbox
+unless you pass `--sandbox=false`.
+
+### Limits
+
+Default `--cap-drop=ALL`, `--security-opt no-new-privileges`,
+`--network=bridge`, `--memory=2g`, `--cpus=2`, `--pids-limit=512`. Override
+any of these in `sandbox.docker.*` in `skvm.config.json`.
+
+`--sandbox` is incompatible with `native` adapter mode (which imports host
+credentials by design) and with `skvm config init|show|doctor` (which
+manage host-side state).
+
 ## Learn more
 
 - **[docs/usage.md](docs/usage.md)** — full command reference: `profile`, `aot-compile`, `run`, `bench`, `jit-optimize`, `proposals`, and more

docker/skvm-sandbox.Dockerfile

@@ -0,0 +1,48 @@
+# syntax=docker/dockerfile:1.7
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    LANG=C.UTF-8 \
+    SKVM_IN_SANDBOX=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates curl git python3 python3-pip nodejs npm jq unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Bun
+RUN curl -fsSL https://bun.sh/install | bash \
+    && mv /root/.bun/bin/bun /usr/local/bin/bun \
+    && chmod +x /usr/local/bin/bun
+
+# opencode — not published on npm; installed from GitHub release binary.
+# Pinned to v1.4.3 (anomalyco/opencode). Matches skvm install/opencode-version.json.
+# SHA-256 verified for linux-x64 asset; bump deliberately and update the hash.
+ARG OPENCODE_VERSION=v1.4.3
+ARG OPENCODE_SHA256=34d503ebb029853293be6fd4d441bbb2dbb03919bfa4525e88b1ca55d68f3e17
+RUN set -e \
+    && curl -fsSL \
+        "https://github.com/anomalyco/opencode/releases/download/${OPENCODE_VERSION}/opencode-linux-x64.tar.gz" \
+        -o /tmp/opencode.tar.gz \
+    && echo "${OPENCODE_SHA256}  /tmp/opencode.tar.gz" | sha256sum -c - \
+    && tar -xzf /tmp/opencode.tar.gz -C /tmp \
+    && mv /tmp/opencode /usr/local/bin/opencode \
+    && chmod +x /usr/local/bin/opencode \
+    && rm /tmp/opencode.tar.gz
+
+# @anthropic-ai/claude-code — published on npm. Pin at known version; bump deliberately.
+RUN npm install -g @anthropic-ai/claude-code@2.1.152
+
+# pi / hermes / openclaw: install paths to be filled in when the image is
+# first built; TODO follow-ups will add them. For now bare-agent + opencode +
+# claude-code is the minimum useful image.
+
+# Baked skvm binary. Build host-side with `bun run build:binary` against the
+# matching skvm version, then copy. (The Dockerfile expects dist/skvm to be a
+# Linux x86_64 binary — cross-compile on the host before docker build.)
+COPY dist/skvm /usr/local/bin/skvm
+RUN chmod +x /usr/local/bin/skvm
+
+WORKDIR /workspace
+
+# Do not bake a USER; the launcher passes -u host-uid:host-gid at run time so
+# bind-mounted writes are owned by the invoking user.

src/cli-config/index.ts

@@ -16,6 +16,9 @@ import { spawnSync } from "node:child_process"
 import path from "node:path"
 import { stdin } from "node:process"
 
+import pkgJson from "../../package.json" with { type: "json" }
+import { resolveImageRef } from "../launcher/image.ts"
+
 import { checkbox, confirm, input, password, select } from "@inquirer/prompts"
 import { createPrompt, isEnterKey, useKeypress, useState } from "@inquirer/core"
 
@@ -37,6 +40,8 @@ import {
   getAdapterRepoDir,
   getAdapterSettings,
   getDefaultAdapterConfigMode,
+  getSandboxConfig,
+  getDefaultSandboxMode,
   detectLegacyHeadlessFields,
   invalidateConfigCache,
   resolveConfigWritePath,
@@ -80,7 +85,7 @@ interface AdapterDraft {
 interface ConfigDraft {
   adapters: Partial<Record<AdapterName, AdapterDraft>>
   providers: { routes: RouteDraft[] }
-  defaults?: { adapterConfigMode?: AdapterConfigMode }
+  defaults?: { adapterConfigMode?: AdapterConfigMode; sandbox?: boolean }
   /**
    * Preserved as an opaque passthrough on re-init — the wizard doesn't
    * configure these fields (credentials and endpoints come from
@@ -231,6 +236,23 @@ async function runShow(): Promise<void> {
   const defMode = getDefaultAdapterConfigMode() ?? "(unset → managed)"
   printRow("Adapter mode", String(defMode), "defaults.adapterConfigMode")
 
+  console.log(c.bold("\nSandbox (Docker):"))
+  try {
+    const sandboxSlice = getSandboxConfig()
+    const sandboxDefaultsOn = getDefaultSandboxMode()
+    console.log(`  Default for new invocations: ${sandboxDefaultsOn ? c.green("on") : c.dim("off")}`)
+    console.log(`  Image:    ${sandboxSlice.docker.image ?? c.dim("(built-in default)")}`)
+    console.log(`  Network:  ${sandboxSlice.docker.network}`)
+    console.log(`  Resources: memory=${sandboxSlice.docker.memory}  cpus=${sandboxSlice.docker.cpus}  pids=${sandboxSlice.docker.pidsLimit}`)
+    const xm = sandboxSlice.docker.extraMounts
+    if (xm.length > 0) {
+      console.log(`  Extra mounts:`)
+      for (const m of xm) console.log(`    ${m.host} → ${m.inner} (${m.mode})`)
+    }
+  } catch (e) {
+    console.log(`  ${c.red("✗")} could not parse: ${String(e)}`)
+  }
+
   console.log(c.bold("\nAdapters"))
   const labelW = Math.max(...ALL_ADAPTERS.map(a => a.length))
   for (const a of ALL_ADAPTERS) {
@@ -409,6 +431,7 @@ async function runInit(): Promise<void> {
       if (action.section === "providers") await stepProviders(draft)
       else if (action.section === "mode") await stepDefaultMode(draft)
       else if (action.section === "adapters") await stepAdapters(draft)
+      else if (action.section === "sandbox") await stepSandbox(draft)
     }
 
     tuiClear()
@@ -533,9 +556,14 @@ function loadExistingDraft(): ConfigDraft {
   }
   if (raw.defaults && typeof raw.defaults === "object") {
     const d = raw.defaults as Record<string, unknown>
+    const restored: ConfigDraft["defaults"] = {}
     if (d.adapterConfigMode === "native" || d.adapterConfigMode === "managed") {
-      draft.defaults = { adapterConfigMode: d.adapterConfigMode }
+      restored.adapterConfigMode = d.adapterConfigMode
+    }
+    if (typeof d.sandbox === "boolean") {
+      restored.sandbox = d.sandbox
     }
+    if (Object.keys(restored).length > 0) draft.defaults = restored
   }
   if (raw.providers && typeof raw.providers === "object") {
     const routes = (raw.providers as { routes?: unknown }).routes
@@ -1066,9 +1094,35 @@ async function pickNativeAgent(opts: {
   })).trim() || def
 }
 
+// --- Step 4: sandbox (Docker) ------------------------------------------------
+
+async function stepSandbox(draft: ConfigDraft): Promise<void> {
+  try {
+    console.log(c.bold("Sandbox (Docker)"))
+    console.log(c.dim("  When --sandbox is set on a command, skvm re-execs itself inside an"))
+    console.log(c.dim("  ephemeral Docker container. You can opt in per-invocation or make"))
+    console.log(c.dim("  sandbox the default for every command."))
+
+    const sandboxDefault = await confirm({
+      message: "Make --sandbox the default for every command?",
+      default: draft.defaults?.sandbox ?? false,
+    })
+
+    draft.defaults = draft.defaults ?? {}
+    draft.defaults.sandbox = sandboxDefault
+
+    if (sandboxDefault) {
+      console.log(c.dim("  (You can opt out of any single invocation with --sandbox=false.)"))
+    }
+  } catch (e) {
+    if (isExit(e)) return
+    throw e
+  }
+}
+
 // --- TUI section pager -------------------------------------------------------
 
-type SectionId = "providers" | "mode" | "adapters" | "write"
+type SectionId = "providers" | "mode" | "adapters" | "sandbox" | "write"
 
 interface Section {
   id: SectionId
@@ -1079,6 +1133,7 @@ const SECTIONS: Section[] = [
   { id: "providers", label: "Providers" },
   { id: "mode", label: "Default mode" },
   { id: "adapters", label: "Adapters" },
+  { id: "sandbox", label: "Sandbox" },
   { id: "write", label: "✓ Write & exit" },
 ]
 
@@ -1130,11 +1185,15 @@ function renderSectionBody(draft: ConfigDraft, index: number): string {
     case "adapters":
       return indent(summarizeAdapters(draft).trimStart())
         + "\n\n  " + c.dim("Press Enter to configure adapters.")
+    case "sandbox":
+      return indent(summarizeSandbox(draft).trimStart())
+        + "\n\n  " + c.dim("Press Enter to configure sandbox defaults.")
     case "write": {
       const full = [
         summarizeProviders(draft),
         summarizeDefaultMode(draft),
         summarizeAdapters(draft),
+        summarizeSandbox(draft),
       ].join("\n")
       const target = shortenPath(CONFIG_WRITE_PATH)
       return indent(full.trimStart())
@@ -1185,6 +1244,11 @@ function summarizeAdapters(draft: ConfigDraft): string {
   return lines.join("\n")
 }
 
+function summarizeSandbox(draft: ConfigDraft): string {
+  const on = draft.defaults?.sandbox === true
+  return `\n${c.bold("Sandbox (Docker):")} default --sandbox ${on ? c.green("on") : c.dim("off")}`
+}
+
 // ---------------------------------------------------------------------------
 // `doctor` — environment health check
 // ---------------------------------------------------------------------------
@@ -1391,6 +1455,48 @@ async function runDoctor(): Promise<void> {
     })
   }
 
+  // Sandbox (Docker) checks — rendered as a separate section after the main
+  // results table so the output groups clearly. `sandboxOk` participates in
+  // the overall exit code only when sandbox is the default for all invocations.
+  let sandboxOk = true
+  const sandboxSectionLines: string[] = []
+  let sandboxSlice
+  try {
+    sandboxSlice = getSandboxConfig()
+  } catch (e) {
+    sandboxSectionLines.push(`  ${c.red("✗")} sandbox slice malformed: ${e}`)
+    sandboxOk = false
+  }
+
+  const sandboxDefaultsOn = getDefaultSandboxMode()
+  sandboxSectionLines.push(`  default --sandbox: ${sandboxDefaultsOn ? "on" : "off"}`)
+
+  const dockerCheck = spawnSync("docker", ["--version"], { encoding: "utf-8" })
+  if (dockerCheck.status === 0) {
+    sandboxSectionLines.push(`  ${c.green("✓")} docker available (${dockerCheck.stdout.trim()})`)
+  } else {
+    const sev = sandboxDefaultsOn ? "✗" : "(info)"
+    sandboxSectionLines.push(`  ${sandboxDefaultsOn ? c.red(sev) : c.dim(sev)} docker not on PATH`)
+    if (sandboxDefaultsOn) sandboxOk = false
+  }
+
+  if (sandboxSlice) {
+    const imageRef = resolveImageRef({
+      cliOverride: null,
+      configImage: sandboxSlice.docker.image,
+      skvmVersion: (pkgJson as { version: string }).version,
+    })
+    const inspect = spawnSync("docker", ["image", "inspect", imageRef], { stdio: "ignore" })
+    if (inspect.status === 0) {
+      sandboxSectionLines.push(`  ${c.green("✓")} image present: ${imageRef}`)
+    } else {
+      const sev = sandboxDefaultsOn ? "✗" : "(info)"
+      sandboxSectionLines.push(`  ${sandboxDefaultsOn ? c.red(sev) : c.dim(sev)} image not pulled: ${imageRef}`)
+      sandboxSectionLines.push(`     build with: docker build -f docker/skvm-sandbox.Dockerfile -t ${imageRef} .`)
+      if (sandboxDefaultsOn) sandboxOk = false
+    }
+  }
+
   // Print results
   console.log()
   let fails = 0, warns = 0
@@ -1406,6 +1512,11 @@ async function runDoctor(): Promise<void> {
   }
   console.log()
 
+  // Sandbox section output
+  console.log(c.bold("Sandbox (Docker):"))
+  for (const line of sandboxSectionLines) console.log(line)
+  console.log()
+
   // Migration note: warn if prior opencode proposals exist but the config
   // does not pin headlessAgent.driver (meaning the user may not have noticed
   // that the default flipped from opencode to pi).
@@ -1420,8 +1531,9 @@ async function runDoctor(): Promise<void> {
     ))
   }
 
-  if (fails > 0) {
-    console.log(c.yellow(`${fails} issue(s) to look at.`) + ` See the items above marked ${c.red("✗")}.`)
+  const totalFails = fails + (sandboxOk ? 0 : 1)
+  if (totalFails > 0) {
+    console.log(c.yellow(`${totalFails} issue(s) to look at.`) + ` See the items above marked ${c.red("✗")}.`)
   } else if (warns > 0) {
     console.log(c.yellow(`${warns} warning(s).`) + " Things should work, but read the notes above.")
   } else {
@@ -1465,8 +1577,11 @@ export { appendDiscoveredRoute } from "../core/config-write.ts"
 function serialize(draft: ConfigDraft): string {
   // Drop empty optional fields so the output stays minimal.
   const out: Record<string, unknown> = {}
-  if (draft.defaults && draft.defaults.adapterConfigMode !== undefined) {
-    out.defaults = { adapterConfigMode: draft.defaults.adapterConfigMode }
+  if (draft.defaults && (draft.defaults.adapterConfigMode !== undefined || draft.defaults.sandbox !== undefined)) {
+    const d: Record<string, unknown> = {}
+    if (draft.defaults.adapterConfigMode !== undefined) d.adapterConfigMode = draft.defaults.adapterConfigMode
+    if (draft.defaults.sandbox !== undefined) d.sandbox = draft.defaults.sandbox
+    out.defaults = d
   }
   const adaptersOut: Record<string, unknown> = {}
   for (const [k, v] of Object.entries(draft.adapters)) {

src/core/cli-flags.ts

@@ -14,6 +14,7 @@ export const GLOBAL_FLAGS: ReadonlySet<string> = new Set([
   "verbose",
   "skvm-cache",
   "skvm-data-dir",
+  "sandbox",
 ])
 
 /**