Add sandbox mode with gitmachine integration

Adds optional sandbox mode where agent tool execution runs inside an
isolated E2B cloud VM via the gitmachine package. The agent (LLM calls)
still runs locally — only tool execution is remote. All changes are
automatically committed to a session branch.

New files:
- src/tools/shared.ts: extracted shared constants, schemas, helpers
- src/sandbox.ts: SandboxConfig/SandboxContext with dynamic import
- src/tools/sandbox-{cli,read,write,memory}.ts: sandbox tool variants
- src/tools/index.ts: createBuiltinTools() factory

CLI: gitclaw --sandbox (requires E2B_API_KEY + GITHUB_TOKEN)
SDK: query({ sandbox: true }) or query({ sandbox: { provider: "e2b" } })

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: shreyas-lyzr

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitclaw",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A universal git-native agent powered by pi-agent-core",
   "type": "module",
   "main": "./dist/exports.js",
@@ -32,6 +32,14 @@
     "@sinclair/typebox": "^0.34.41",
     "js-yaml": "^4.1.0"
   },
+  "peerDependencies": {
+    "gitmachine": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "gitmachine": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",

src/exports.ts

@@ -5,6 +5,7 @@ export { query, tool } from "./sdk.js";
 export type {
 	Query,
 	QueryOptions,
+	SandboxOptions,
 	GCMessage,
 	GCAssistantMessage,
 	GCUserMessage,
@@ -27,5 +28,9 @@ export type { SubAgentMetadata } from "./agents.js";
 export type { ComplianceWarning } from "./compliance.js";
 export type { EnvConfig } from "./config.js";
 
+// Sandbox
+export type { SandboxConfig, SandboxContext } from "./sandbox.js";
+export { createSandboxContext } from "./sandbox.js";
+
 // Loader (escape hatch)
 export { loadAgent } from "./loader.js";

src/index.ts

@@ -4,10 +4,9 @@ import { createInterface } from "readline";
 import { Agent } from "@mariozechner/pi-agent-core";
 import type { AgentEvent, AgentTool } from "@mariozechner/pi-agent-core";
 import { loadAgent } from "./loader.js";
-import { createCliTool } from "./tools/cli.js";
-import { createReadTool } from "./tools/read.js";
-import { createWriteTool } from "./tools/write.js";
-import { createMemoryTool } from "./tools/memory.js";
+import { createBuiltinTools } from "./tools/index.js";
+import { createSandboxContext } from "./sandbox.js";
+import type { SandboxContext, SandboxConfig } from "./sandbox.js";
 import { expandSkillCommand } from "./skills.js";
 import { loadHooksConfig, runHooks, wrapToolWithHooks } from "./hooks.js";
 import type { HooksConfig } from "./hooks.js";
@@ -24,12 +23,13 @@ const bold = (s: string) => `\x1b[1m${s}\x1b[0m`;
 const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
 const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
 
-function parseArgs(argv: string[]): { model?: string; dir: string; prompt?: string; env?: string } {
+function parseArgs(argv: string[]): { model?: string; dir: string; prompt?: string; env?: string; sandbox?: boolean } {
 	const args = argv.slice(2);
 	let model: string | undefined;
 	let dir = process.cwd();
 	let prompt: string | undefined;
 	let env: string | undefined;
+	let sandbox = false;
 
 	for (let i = 0; i < args.length; i++) {
 		switch (args[i]) {
@@ -49,6 +49,10 @@ function parseArgs(argv: string[]): { model?: string; dir: string; prompt?: stri
 			case "-e":
 				env = args[++i];
 				break;
+			case "--sandbox":
+			case "-s":
+				sandbox = true;
+				break;
 			default:
 				if (!args[i].startsWith("-")) {
 					prompt = args[i];
@@ -57,7 +61,7 @@ function parseArgs(argv: string[]): { model?: string; dir: string; prompt?: stri
 		}
 	}
 
-	return { model, dir, prompt, env };
+	return { model, dir, prompt, env, sandbox };
 }
 
 function handleEvent(
@@ -235,7 +239,7 @@ async function ensureRepo(dir: string, model?: string): Promise<string> {
 }
 
 async function main(): Promise<void> {
-	const { model, dir: rawDir, prompt, env } = parseArgs(process.argv);
+	const { model, dir: rawDir, prompt, env, sandbox: useSandbox } = parseArgs(process.argv);
 
 	// If no --dir given interactively, ask for it
 	let dir = rawDir;
@@ -246,8 +250,22 @@ async function main(): Promise<void> {
 		}
 	}
 
-	// Ensure the target is a valid gitclaw repo
-	dir = await ensureRepo(dir, model);
+	// Create sandbox context if --sandbox flag is set
+	let sandboxCtx: SandboxContext | undefined;
+	if (useSandbox) {
+		const sandboxConfig: SandboxConfig = { provider: "e2b" };
+		sandboxCtx = await createSandboxContext(sandboxConfig, resolve(dir));
+		console.log(dim("Starting sandbox VM..."));
+		await sandboxCtx.gitMachine.start();
+		console.log(dim(`Sandbox ready (repo: ${sandboxCtx.repoPath})`));
+	}
+
+	// Ensure the target is a valid gitclaw repo (skip in sandbox mode — gitmachine clones the repo)
+	if (!useSandbox) {
+		dir = await ensureRepo(dir, model);
+	} else {
+		dir = resolve(dir);
+	}
 
 	let loaded;
 	try {
@@ -312,12 +330,11 @@ async function main(): Promise<void> {
 	}
 
 	// Build tools — built-in + declarative
-	let tools: AgentTool<any>[] = [
-		createCliTool(dir, manifest.runtime.timeout),
-		createReadTool(dir),
-		createWriteTool(dir),
-		createMemoryTool(dir),
-	];
+	let tools: AgentTool<any>[] = createBuiltinTools({
+		dir,
+		timeout: manifest.runtime.timeout,
+		sandbox: sandboxCtx,
+	});
 
 	// Load declarative tools from tools/*.yaml (Phase 2.2)
 	const declarativeTools = await loadDeclarativeTools(agentDir);
@@ -380,6 +397,11 @@ async function main(): Promise<void> {
 				}).catch(() => {});
 			}
 			throw err;
+		} finally {
+			if (sandboxCtx) {
+				console.log(dim("Stopping sandbox..."));
+				await sandboxCtx.gitMachine.stop();
+			}
 		}
 		return;
 	}
@@ -401,6 +423,7 @@ async function main(): Promise<void> {
 
 			if (trimmed === "/quit" || trimmed === "/exit") {
 				rl.close();
+				await stopSandbox();
 				process.exit(0);
 			}
 
@@ -463,14 +486,22 @@ async function main(): Promise<void> {
 		});
 	};
 
+	// Sandbox cleanup helper
+	const stopSandbox = async () => {
+		if (sandboxCtx) {
+			console.log(dim("Stopping sandbox..."));
+			await sandboxCtx.gitMachine.stop();
+		}
+	};
+
 	// Handle Ctrl+C during streaming
 	rl.on("SIGINT", () => {
 		if (agent.state.isStreaming) {
 			agent.abort();
 		} else {
 			console.log("\nBye!");
 			rl.close();
-			process.exit(0);
+			stopSandbox().finally(() => process.exit(0));
 		}
 	});
 

src/sandbox.ts

@@ -0,0 +1,94 @@
+import { execSync } from "child_process";
+
+// ── Types ───────────────────────────────────────────────────────────────
+
+export interface SandboxConfig {
+	provider: "e2b";
+	template?: string;
+	timeout?: number;
+	repository?: string;
+	token?: string;
+	session?: string;
+	autoCommit?: boolean;
+	envs?: Record<string, string>;
+}
+
+/**
+ * Wraps the gitmachine GitMachine + Machine instances.
+ * Types are `any` because gitmachine is an optional peer dependency
+ * loaded via dynamic import — we don't have compile-time types.
+ */
+export interface SandboxContext {
+	/** GitMachine instance (gitmachine) — provides run(), commit(), start(), stop() */
+	gitMachine: any;
+	/** Underlying Machine instance — provides readFile(), writeFile() */
+	machine: any;
+	/** Absolute path to the repo root inside the sandbox (e.g. /home/user/repo) */
+	repoPath: string;
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────
+
+function detectRepoUrl(dir: string): string | null {
+	try {
+		return execSync("git remote get-url origin", { cwd: dir, stdio: "pipe" })
+			.toString()
+			.trim();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Create a SandboxContext by dynamically importing gitmachine.
+ * Throws a clear error if gitmachine is not installed.
+ */
+export async function createSandboxContext(
+	config: SandboxConfig,
+	dir: string,
+): Promise<SandboxContext> {
+	let gitmachine: any;
+	try {
+		// @ts-ignore — gitmachine is an optional peer dependency
+		gitmachine = await import("gitmachine");
+	} catch {
+		throw new Error(
+			"Sandbox mode requires the 'gitmachine' package.\n" +
+			"Install it with: npm install gitmachine",
+		);
+	}
+
+	const token = config.token
+		|| process.env.GITHUB_TOKEN
+		|| process.env.GIT_TOKEN;
+
+	const repository = config.repository || detectRepoUrl(dir);
+	if (!repository) {
+		throw new Error(
+			"Sandbox mode requires a repository URL. Provide it via --sandbox config, " +
+			"or ensure the working directory has a git remote named 'origin'.",
+		);
+	}
+
+	const gitMachine = new gitmachine.GitMachine({
+		provider: config.provider,
+		template: config.template,
+		timeout: config.timeout,
+		repository,
+		token,
+		session: config.session,
+		autoCommit: config.autoCommit ?? true,
+		envs: config.envs,
+	});
+
+	// The repo path inside the sandbox is determined by gitmachine after start().
+	// Convention: /home/user/<repo-name>
+	const repoName = repository.split("/").pop()?.replace(/\.git$/, "") || "repo";
+	const repoPath = `/home/user/${repoName}`;
+
+	return {
+		gitMachine,
+		machine: gitMachine.machine,
+		repoPath,
+	};
+}

src/sdk-types.ts

@@ -100,6 +100,19 @@ export interface GCToolDefinition {
 	handler: (args: any, signal?: AbortSignal) => Promise<string | { text: string; details?: any }>;
 }
 
+// ── Sandbox options ─────────────────────────────────────────────────────
+
+export interface SandboxOptions {
+	provider: "e2b";
+	template?: string;
+	timeout?: number;
+	repository?: string;
+	token?: string;
+	session?: string;
+	autoCommit?: boolean;
+	envs?: Record<string, string>;
+}
+
 // ── Query options ──────────────────────────────────────────────────────
 
 export interface QueryOptions {
@@ -113,6 +126,7 @@ export interface QueryOptions {
 	replaceBuiltinTools?: boolean;
 	allowedTools?: string[];
 	disallowedTools?: string[];
+	sandbox?: SandboxOptions | boolean;
 	hooks?: GCHooks;
 	maxTurns?: number;
 	abortController?: AbortController;

src/sdk.ts

@@ -3,10 +3,9 @@ import type { AgentEvent, AgentTool } from "@mariozechner/pi-agent-core";
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import { loadAgent } from "./loader.js";
 import type { AgentManifest } from "./loader.js";
-import { createCliTool } from "./tools/cli.js";
-import { createReadTool } from "./tools/read.js";
-import { createWriteTool } from "./tools/write.js";
-import { createMemoryTool } from "./tools/memory.js";
+import { createBuiltinTools } from "./tools/index.js";
+import { createSandboxContext } from "./sandbox.js";
+import type { SandboxContext } from "./sandbox.js";
 import { loadHooksConfig, runHooks, wrapToolWithHooks } from "./hooks.js";
 import { loadDeclarativeTools } from "./tool-loader.js";
 import { buildTypeboxSchema } from "./tool-loader.js";
@@ -18,6 +17,7 @@ import type {
 	GCHookContext,
 	Query,
 	QueryOptions,
+	SandboxOptions,
 } from "./sdk-types.js";
 
 // ── Event channel ──────────────────────────────────────────────────────
@@ -118,6 +118,9 @@ export function query(options: QueryOptions): Query {
 		channel.push(msg);
 	}
 
+	// Sandbox context (hoisted for cleanup in catch)
+	let sandboxCtx: SandboxContext | undefined;
+
 	// Async initialization + run
 	const runPromise = (async () => {
 		const dir = options.dir ?? process.cwd();
@@ -136,16 +139,23 @@ export function query(options: QueryOptions): Query {
 			systemPrompt += "\n\n" + options.systemPromptSuffix;
 		}
 
-		// 3. Build tools
+		// 3. Build tools (with optional sandbox)
+		if (options.sandbox) {
+			const sandboxConfig: SandboxOptions = options.sandbox === true
+				? { provider: "e2b" }
+				: options.sandbox;
+			sandboxCtx = await createSandboxContext(sandboxConfig, dir);
+			await sandboxCtx.gitMachine.start();
+		}
+
 		let tools: AgentTool<any>[] = [];
 
 		if (!options.replaceBuiltinTools) {
-			tools = [
-				createCliTool(dir, loaded.manifest.runtime.timeout),
-				createReadTool(dir),
-				createWriteTool(dir),
-				createMemoryTool(dir),
-			];
+			tools = createBuiltinTools({
+				dir,
+				timeout: loaded.manifest.runtime.timeout,
+				sandbox: sandboxCtx,
+			});
 		}
 
 		// Declarative tools from tools/*.yaml
@@ -387,9 +397,19 @@ export function query(options: QueryOptions): Query {
 			}
 		}
 
+		// Stop sandbox if active
+		if (sandboxCtx) {
+			await sandboxCtx.gitMachine.stop().catch(() => {});
+		}
+
 		// Ensure channel finishes even if no agent_end event
 		channel.finish();
-	})().catch((err) => {
+	})().catch(async (err) => {
+		// Stop sandbox on error
+		if (sandboxCtx) {
+			await sandboxCtx.gitMachine.stop().catch(() => {});
+		}
+
 		// Fire on_error hooks
 		if (options.hooks?.onError) {
 			Promise.resolve(options.hooks.onError({