Add claude-code-sandbox example

Runs Claude Code headless against a real Git checkout inside a disposable
Tenki microVM, then reads back the diff the agent produced.

verify.mjs proves the Tenki-facing half with no model key: boot with
cloneRepoUrl, npm i -g the CLI, assert its version, edit a file in the
checkout, assert the diff round-trips.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uz85xGA4zWSge1BtiDNnSN

Author: claude

README.md

@@ -59,6 +59,7 @@ Give an agent a sandboxed place to run the code it writes.
 | Example | Integration |
 | --- | --- |
 | [MCP server](examples/mcp-tenki-sandbox/) | Sandbox tools for Claude, Cursor, or any MCP client |
+| [Claude Code](examples/claude-code-sandbox/) | Headless coding agent on a real repo checkout |
 | [Composio](examples/composio-tenki/) | Tenki tools in a Composio agent |
 | [Covalent](examples/covalent-tenki/) | Each workflow task in its own microVM |
 | [AgentBox](examples/agentbox-tenki/) | Coding-agent boxes as Firecracker microVMs |

examples/claude-code-sandbox/README.md

@@ -0,0 +1,66 @@
+# Claude Code on Tenki (headless, on a real repo)
+
+Run Claude Code non-interactively against a real Git checkout inside a disposable [Tenki Sandbox](https://tenki.cloud/products/sandbox) microVM, then read back the diff the agent produced and throw the machine away.
+
+## The code (`run.mjs`)
+
+```js
+import { TenkiSandbox, stdoutText } from "@tenkicloud/sandbox";
+
+const REPO = "https://github.com/sindresorhus/yocto-queue";
+const TASK = "Add a toArray() method to the Queue class in index.js that returns the queued values as an array, oldest first. Declare it in index.d.ts and add a test for it in test.js.";
+const PASSTHROUGH = ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL"];
+
+const tenki = new TenkiSandbox({ authToken: process.env.TENKI_AUTH_TOKEN });
+
+// cloneRepoUrl checks the repo out to ./repo before createAndWait resolves.
+await using sandbox = await tenki.createAndWait({
+  cpuCores: 2,
+  memoryMb: 4096,
+  cloneRepoUrl: REPO,
+  workspaceId: process.env.TENKI_WORKSPACE_ID,
+});
+
+// Outbound is on by default, so no allowOutbound is needed to reach the npm registry.
+await sandbox.exec("npm", { args: ["i", "-g", "@anthropic-ai/claude-code"] });
+
+const decoder = new TextDecoder();
+await sandbox.exec("claude", {
+  // Skipping permission prompts is what the throwaway VM buys you: the agent gets a
+  // free hand on a machine whose entire filesystem you delete at the end of this script.
+  args: ["-p", TASK, "--dangerously-skip-permissions"],
+  cwd: "repo", // relative paths resolve under the workdir, /home/tenki
+  timeoutMs: 10 * 60_000,
+  env: Object.fromEntries(PASSTHROUGH.filter((k) => process.env[k]).map((k) => [k, process.env[k]])),
+  onOutput: ({ data }) => process.stdout.write(decoder.decode(data)), // data is a Uint8Array
+});
+
+// sandbox.git.* runs at the workdir, and the checkout is one level down — so use `git -C`.
+console.log(stdoutText(await sandbox.exec("git", { args: ["-C", "repo", "diff"] })));
+```
+
+The last line is the point: a unified diff against a real upstream checkout, produced by an agent that had root-free run of a machine you are about to delete.
+
+## Run it
+
+```bash
+npm install
+export TENKI_AUTH_TOKEN=...      # from `tenki login` (~/.config/tenki/config.yaml)
+export TENKI_WORKSPACE_ID=...
+export ANTHROPIC_API_KEY=...     # the agent turn; ANTHROPIC_MODEL is optional
+node run.mjs                     # streams the agent's turn, then prints the diff
+```
+
+Verify the Tenki half without a model key — this is what CI runs:
+
+```bash
+node verify.mjs   # create + clone → install the CLI → read its version → edit → git diff
+```
+
+## Notes
+
+- **`sandbox.git.*` runs at the sandbox workdir (`/home/tenki`), but `cloneRepoUrl` checks out one level down into `./repo`** — so `sandbox.git.diff()` fails with "not a git repository". Read the checkout with `sandbox.exec("git", { args: ["-C", "repo", "diff"] })`, or clone at the workdir root if you want the helpers.
+- The default image already ships Node 24, npm 11, and git 2.43, and outbound network is on for a bare `create`. `npm i -g @anthropic-ai/claude-code` finishes in about five seconds — no `allowOutbound`, no custom image, no baked-in CLI.
+- `--dangerously-skip-permissions` refuses to run as root; the sandbox user is `tenki`, so it works as written. It is the right flag *here* precisely because the blast radius is one microVM.
+- `exec(command, { args })` runs a bare binary and its args with no shell splitting, so the whole task prompt goes through as a single argument. `ExecOptions.env` is scoped to that one process — the model key never lands in the repo or the image.
+- Secrets in, diffs out: nothing else from your shell crosses into the VM, and `await using` terminates it when the scope ends (`Session` is an `AsyncDisposable`). Requires Node 20+.

examples/claude-code-sandbox/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "claude-code-sandbox",
+  "private": true,
+  "type": "module",
+  "description": "Cookbook example — run Claude Code headless against a real repo in a disposable Tenki sandbox.",
+  "dependencies": {
+    "@tenkicloud/sandbox": "^0.4.0"
+  }
+}

examples/claude-code-sandbox/run.mjs

@@ -0,0 +1,34 @@
+// Claude Code, headless, on a real repo in a disposable Tenki sandbox:
+// clone -> install the CLI -> let the agent edit the checkout -> read back the diff.
+import { TenkiSandbox, stdoutText } from "@tenkicloud/sandbox";
+
+const REPO = "https://github.com/sindresorhus/yocto-queue";
+const TASK = "Add a toArray() method to the Queue class in index.js that returns the queued values as an array, oldest first. Declare it in index.d.ts and add a test for it in test.js.";
+const PASSTHROUGH = ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL"];
+
+const tenki = new TenkiSandbox({ authToken: process.env.TENKI_AUTH_TOKEN });
+
+// cloneRepoUrl checks the repo out to ./repo before createAndWait resolves.
+await using sandbox = await tenki.createAndWait({
+	cpuCores: 2,
+	memoryMb: 4096,
+	cloneRepoUrl: REPO,
+	workspaceId: process.env.TENKI_WORKSPACE_ID,
+});
+
+// Outbound is on by default, so no allowOutbound is needed to reach the npm registry.
+await sandbox.exec("npm", { args: ["i", "-g", "@anthropic-ai/claude-code"] });
+
+const decoder = new TextDecoder();
+await sandbox.exec("claude", {
+	// Skipping permission prompts is what the throwaway VM buys you: the agent gets a
+	// free hand on a machine whose entire filesystem you delete at the end of this script.
+	args: ["-p", TASK, "--dangerously-skip-permissions"],
+	cwd: "repo", // relative paths resolve under the workdir, /home/tenki
+	timeoutMs: 10 * 60_000,
+	env: Object.fromEntries(PASSTHROUGH.filter((k) => process.env[k]).map((k) => [k, process.env[k]])),
+	onOutput: ({ data }) => process.stdout.write(decoder.decode(data)), // data is a Uint8Array
+});
+
+// sandbox.git.* runs at the workdir, and the checkout is one level down — so use `git -C`.
+console.log(stdoutText(await sandbox.exec("git", { args: ["-C", "repo", "diff"] })));

examples/claude-code-sandbox/verify.mjs

@@ -0,0 +1,66 @@
+/**
+ * Proves the Tenki-facing half of this example without a model key: boot a sandbox
+ * with the repo cloned, install the Claude Code CLI, read its version back, edit a
+ * file in the checkout, and assert the diff round-trips. (run.mjs's agent turn needs
+ * ANTHROPIC_API_KEY; CONTRIBUTING says CI verifies the backend, not the model.)
+ * Token/workspace from env (CI) or ~/.config/tenki/config.yaml (local `tenki login`).
+ */
+import { TenkiSandbox, stdoutText } from "@tenkicloud/sandbox";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+
+const cfg = (key) => {
+	try {
+		const c = readFileSync(`${homedir()}/.config/tenki/config.yaml`, "utf8");
+		return (c.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1] ?? "").trim();
+	} catch {
+		return "";
+	}
+};
+
+const authToken = process.env.TENKI_AUTH_TOKEN || process.env.TENKI_API_KEY || cfg("auth_token");
+const workspaceId = process.env.TENKI_WORKSPACE_ID || cfg("current_workspace_id");
+if (!authToken) {
+	console.error("No token. Set TENKI_AUTH_TOKEN, or run `tenki login`.");
+	process.exit(1);
+}
+
+const tenki = new TenkiSandbox({ authToken });
+let sandbox;
+try {
+	sandbox = await tenki.createAndWait({
+		cpuCores: 2,
+		memoryMb: 4096,
+		cloneRepoUrl: "https://github.com/sindresorhus/yocto-queue",
+		workspaceId,
+	});
+
+	const pkg = JSON.parse(stdoutText(await sandbox.exec("cat", { args: ["repo/package.json"] })));
+	if (pkg.name !== "yocto-queue") throw new Error(`clone landed wrong: repo/package.json is ${pkg.name}`);
+
+	const install = await sandbox.exec("npm", { args: ["i", "-g", "@anthropic-ai/claude-code"], timeoutMs: 300_000 });
+	if (install.exitCode !== 0) throw new Error(`npm i -g @anthropic-ai/claude-code exited ${install.exitCode}`);
+
+	const version = stdoutText(await sandbox.exec("claude", { args: ["--version"] })).trim();
+	if (!/^\d+\.\d+\.\d+ \(Claude Code\)$/.test(version)) throw new Error(`claude --version said ${JSON.stringify(version)}`);
+
+	// Stand in for the agent's edit, then read it back the way run.mjs reads the agent's.
+	await sandbox.exec("sh", { args: ["-c", "printf '\\nexport const verified = true;\\n' >> repo/index.js"] });
+	const diff = stdoutText(await sandbox.exec("git", { args: ["-C", "repo", "diff"] }));
+	if (!diff.includes("--- a/index.js") || !diff.includes("+export const verified = true;")) {
+		throw new Error(`diff did not round-trip: ${JSON.stringify(diff.slice(0, 200))}`);
+	}
+
+	console.log(`✓ claude-code-sandbox: create + clone → npm i -g claude-code → ${version} → edit → git diff → dispose`);
+} catch (e) {
+	console.error("✗ " + (e?.message ?? e));
+	process.exitCode = 1;
+} finally {
+	if (sandbox) {
+		try {
+			await sandbox[Symbol.asyncDispose]();
+		} catch {
+			/* self-reaps via idle/lifetime caps */
+		}
+	}
+}