windows-development-sandbox 0.0.0-stage → 1.0.5

package/.sandbox-config.example.json

@@ -0,0 +1,14 @@
+{
+  "harness": "claude",
+  "sandbox": { "memoryMb": "auto", "headless": false },
+  "provisioning": { "git": { "access": "readonly" } },
+  "toolchains": {
+    "node": { "version": "20", "extraVersions": ["18"] },
+    "python": { "version": "3.12" },
+    "rust": { "enabled": false }
+  },
+  "mappings": [
+    { "host": "D:\\Assets\\textures", "guest": "C:\\Assets", "readOnly": true, "optional": true }
+  ],
+  "scripts": []
+}

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Windows Development Sandbox
+
+**A throwaway Windows machine for every project, with or without an AI agent.**
+
+[![Release](https://img.shields.io/github/v/release/JoshDiDuca/agent-sandbox?label=release)](https://github.com/JoshDiDuca/agent-sandbox/releases/latest)
+[![CI](https://github.com/JoshDiDuca/agent-sandbox/actions/workflows/ci.yml/badge.svg)](https://github.com/JoshDiDuca/agent-sandbox/actions/workflows/ci.yml)
+![Windows 10/11 Pro, Enterprise, Education](https://img.shields.io/badge/Windows-10%20%7C%2011%20Pro-0078D4)
+![MIT](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+Run it in a project folder and you get a clean [Windows Sandbox](https://learn.microsoft.com/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview)
+where that folder is the workspace, the tools and databases the project needs install themselves, and nothing else
+on your PC is reachable. Close it and it's gone. Your project, tools, databases and logins are kept for next time.
+
+## Install
+
+```powershell
+irm https://github.com/JoshDiDuca/agent-sandbox/releases/latest/download/install.ps1 | iex
+```
+
+It checks your PC, offers to turn on Windows Sandbox, and installs everything. It uses your Node.js 20+ if you have it,
+otherwise a private copy just for this tool. Nothing is installed system-wide.
+Needs Windows 10/11 **Pro, Enterprise or Education**. [Other ways to install](docs/install.md)
+
+## Use
+
+```powershell
+cd C:\code\my-app
+
+sandbox            # menu: start an agent, a plain sandbox, diagnostics, cleanup ...
+sandbox claude     # Claude Code in a sandbox for this folder (or: claude-sandbox)
+sandbox claude -t  # ... in this terminal (Ctrl+] detaches, the session keeps running)
+sandbox start      # just the sandbox, no agent
+sandbox opencode   # any supported agent by name
+```
+
+The first start downloads what the project needs (a few minutes, once). After that, starts take seconds.
+
+> `claude-sbx`, `codex-sbx`, `gemini-sbx` and `agent-sandbox` are the old command names. They still work for now; use
+> `sandbox <agent>` / `claude-sandbox` and `sandbox` instead.
+
+## What you get
+
+|  |  |
+|---|---|
+| **Safe by default** | The agent sees only your project folder. Credentials are stripped before anything is copied in, your LAN is blocked, and nothing the sandbox writes can run on your PC. |
+| **Languages** | Node, Python, Rust, C/C++ (GCC or MSVC), .NET (incl. .NET Framework targeting), Go, Java, Ruby, PHP, Deno, Bun, PowerShell 7, with pnpm, yarn, Volta, uv, pyenv, Maven, Gradle, Composer, gh ... |
+| **Databases** | PostgreSQL, MySQL, MongoDB, Redis and DynamoDB Local with a web UI, started only when the project uses them |
+| **Agents** | Claude Code, Codex, Gemini, opencode, Qwen, Crush, Copilot, Kilo, Amp, Cline, Continue, Kimi, Aider, DeepSeek agents |
+| **Smart** | Detects what the project needs from its files, respects version files, installs in parallel and reuses everything |
+| **Feels like home** | Your desktop look, Claude settings, MCP servers and conversation history come along; history syncs back |
+
+## Commands
+
+| Command | |
+|---|---|
+| `sandbox` | the interactive menu: repeat your last command, start agents, every option, and all settings |
+| `sandbox <agent>`, `claude-sandbox` | start an agent; `-t` for this terminal, `--headless` for no window |
+| `sandbox start` | the sandbox without an agent |
+| `sandbox attach` / `sessions` / `status` | work with a running sandbox |
+| `sandbox exec -- <cmd>` | run a command inside |
+| `sandbox stop` / `hide` / `show` | shut down, hide or show the window |
+| `sandbox data` / `data clean` | what's stored and how big, and freeing space |
+| `sandbox setup` / `doctor` / `repair` | check this PC, see what will be installed, fix common problems |
+
+All commands and options: [docs/commands.md](docs/commands.md)
+
+## Documentation
+
+- [Install](docs/install.md): requirements, other ways to install, upgrading
+- [Commands](docs/commands.md): every command and option, the menu, sessions and attaching
+- [Tools and databases](docs/toolchains.md): languages, package managers, databases, agents, what is tested
+- [Configuration](docs/configuration.md): settings, project files, paths, accounts, hooks
+- [Security](docs/security.md): how your PC is protected, secrets, git access
+- [Troubleshooting](docs/troubleshooting.md): common problems and fixes
+- [Development](docs/development.md): building, testing, releasing (code layout in [CLAUDE.md](CLAUDE.md))

package/config.example.json

@@ -0,0 +1,332 @@
+{
+  "$schema": "./schemas/config.schema.json",
+  "defaultHarness": "claude",
+  "guestWorkspace": "auto",
+  "readOnly": false,
+  "mappings": [],
+  "sandbox": {
+    "memoryMb": "auto",
+    "maxMemoryMb": 32768,
+    "reserveHostMb": 8192,
+    "vGpu": false,
+    "networking": true,
+    "clipboard": true,
+    "audioInput": false,
+    "videoInput": false,
+    "printerRedirection": false,
+    "protectedClient": true,
+    "headless": false
+  },
+  "storage": {
+    "root": "%LOCALAPPDATA%\\AgentSandbox",
+    "persistAgentState": true,
+    "dataName": "default"
+  },
+  "network": {
+    "blockPrivateRanges": true
+  },
+  "provisioning": {
+    "copyFromHost": true,
+    "fallbackToInstall": true,
+    "refresh": false,
+    "git": {
+      "enabled": true,
+      "access": "full"
+    },
+    "terminal": {
+      "enabled": true
+    }
+  },
+  "toolchains": {
+    "node": {
+      "version": "host",
+      "extraVersions": [],
+      "corepack": true,
+      "volta": "auto",
+      "globalPackages": []
+    },
+    "python": {
+      "enabled": "auto",
+      "version": "3",
+      "python2": true,
+      "pyenv": "auto",
+      "tools": []
+    },
+    "rust": {
+      "enabled": "auto",
+      "toolchain": "stable",
+      "host": "auto",
+      "components": [],
+      "targets": [],
+      "crates": [],
+      "targetDir": "separate"
+    },
+    "msvc": {
+      "enabled": "auto",
+      "acceptLicense": false,
+      "msvcVersion": "latest",
+      "sdkVersion": "latest"
+    },
+    "cpp": {
+      "enabled": "auto",
+      "flexBison": true
+    },
+    "dotnet": {
+      "enabled": "auto",
+      "channels": [
+        "LTS"
+      ],
+      "tools": [],
+      "workloads": [],
+      "frameworkTargets": [
+        "net48",
+        "net472"
+      ],
+      "netfx35": false
+    },
+    "go": {
+      "enabled": "auto",
+      "version": "stable",
+      "tools": []
+    },
+    "java": {
+      "enabled": "auto",
+      "version": "lts",
+      "maven": true,
+      "gradle": true
+    },
+    "ruby": {
+      "enabled": "auto",
+      "version": "3",
+      "gems": []
+    },
+    "php": {
+      "enabled": "auto",
+      "version": "8",
+      "composer": true
+    },
+    "deno": {
+      "enabled": "auto"
+    },
+    "pwsh": {
+      "enabled": "auto"
+    },
+    "cli": {
+      "gh": "auto",
+      "zstd": false,
+      "openssl": "auto"
+    },
+    "bun": {
+      "enabled": true
+    },
+    "uv": {
+      "enabled": true
+    },
+    "vcRuntime": {
+      "enabled": false
+    },
+    "mesa": {
+      "enabled": false,
+      "vulkan": false
+    },
+    "vscode": {
+      "enabled": true
+    },
+    "environment": {}
+  },
+  "databases": {
+    "postgres": {
+      "enabled": "auto",
+      "version": "latest",
+      "port": 5432
+    },
+    "mysql": {
+      "enabled": "auto",
+      "version": "lts",
+      "port": 3306
+    },
+    "mongodb": {
+      "enabled": "auto",
+      "version": "latest",
+      "port": 27017
+    },
+    "redis": {
+      "enabled": "auto",
+      "port": 6379
+    },
+    "dynamodb": {
+      "enabled": "auto",
+      "port": 8000,
+      "adminPort": 8001,
+      "admin": true
+    },
+    "sqlserver": {
+      "enabled": "auto"
+    }
+  },
+  "attach": {
+    "enabled": true,
+    "reuseSession": true,
+    "auto": false,
+    "autoHide": false
+  },
+  "secrets": {
+    "strip": true,
+    "allow": [],
+    "patterns": [],
+    "warnFiles": true
+  },
+  "personalization": {
+    "enabled": true
+  },
+  "claudeProfile": {
+    "enabled": true,
+    "hostDir": "auto",
+    "include": [
+      "settings.json",
+      "CLAUDE.md",
+      "commands",
+      "agents",
+      "skills",
+      "plugins"
+    ],
+    "globalStateFile": "auto",
+    "copyCredentials": false,
+    "overwrite": true,
+    "syncHistory": true,
+    "syncClaudeMem": true
+  },
+  "harnesses": {
+    "claude": {
+      "hostExecutable": "claude.exe",
+      "hostDir": "auto",
+      "npmPackage": "@anthropic-ai/claude-code@latest",
+      "npmBin": "claude",
+      "arguments": [],
+      "environment": {
+        "DISABLE_AUTOUPDATER": "1"
+      },
+      "resumeArguments": [
+        "--continue"
+      ]
+    },
+    "codex": {
+      "npmPackage": "@openai/codex@latest",
+      "npmBin": "codex",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "resume",
+        "--last"
+      ]
+    },
+    "gemini": {
+      "npmPackage": "@google/gemini-cli@latest",
+      "npmBin": "gemini",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--resume"
+      ]
+    },
+    "opencode": {
+      "npmPackage": "opencode-ai@latest",
+      "npmBin": "opencode",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--continue"
+      ]
+    },
+    "qwen": {
+      "npmPackage": "@qwen-code/qwen-code@latest",
+      "npmBin": "qwen",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--continue"
+      ]
+    },
+    "crush": {
+      "npmPackage": "@charmland/crush@latest",
+      "npmBin": "crush",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--continue"
+      ]
+    },
+    "copilot": {
+      "npmPackage": "@github/copilot@latest",
+      "npmBin": "copilot",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--continue"
+      ]
+    },
+    "kilo": {
+      "npmPackage": "@kilocode/cli@latest",
+      "npmBin": "kilo",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--continue"
+      ]
+    },
+    "amp": {
+      "npmPackage": "@ampcode/cli@latest",
+      "npmBin": "amp",
+      "arguments": [],
+      "environment": {}
+    },
+    "cline": {
+      "npmPackage": "cline@latest",
+      "npmBin": "cline",
+      "arguments": [],
+      "environment": {}
+    },
+    "continue": {
+      "npmPackage": "@continuedev/cli@latest",
+      "npmBin": "cn",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--resume"
+      ]
+    },
+    "kimi": {
+      "npmPackage": "@moonshot-ai/kimi-code@latest",
+      "npmBin": "kimi",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "-c"
+      ]
+    },
+    "reasonix": {
+      "npmPackage": "reasonix@latest",
+      "npmBin": "reasonix",
+      "arguments": [],
+      "environment": {}
+    },
+    "deepseek": {
+      "npmPackage": "codewhale@latest",
+      "npmBin": "codewhale",
+      "arguments": [],
+      "environment": {}
+    },
+    "aider": {
+      "uvPackage": "aider-chat",
+      "uvBin": "aider",
+      "arguments": [],
+      "environment": {},
+      "resumeArguments": [
+        "--restore-chat-history"
+      ]
+    }
+  },
+  "hooks": {
+    "failFast": false
+  }
+}

package/dist/api.d.ts

@@ -0,0 +1,31 @@
+import type { GuestResponse, SandboxStatus, SessionStatus } from './core/types.js';
+export interface SandboxClient {
+    /** True while a Windows Sandbox is running. */
+    isRunning(): boolean;
+    /** Boot status written by the sandbox (null if it never started). */
+    status(): SandboxStatus | null;
+    /** Waits until provisioning is finished. */
+    ready(): Promise<SandboxStatus>;
+    sessions(): SessionStatus[];
+    /** Runs a command inside the sandbox; `cwd` is a guest path inside the workspace (default: the workspace). */
+    exec(command: string[], options?: {
+        cwd?: string;
+        timeoutSeconds?: number;
+    }): Promise<GuestResponse>;
+    /** Starts another agent session (its own terminal tab in the sandbox) and resolves once it is running. */
+    startSession(options?: {
+        harness?: string;
+        args?: string[];
+        cwd?: string;
+    }): Promise<SessionStatus>;
+    /** Restarts running sessions in place (they resume their conversation). */
+    restart(harness?: string): Promise<GuestResponse>;
+    ping(): Promise<GuestResponse>;
+    /** Bridges the current terminal to a session (interactive programs only). */
+    attach(sessionId?: string): Promise<number>;
+}
+export declare const sandbox: (options?: {
+    config?: string;
+}) => SandboxClient;
+export type { GuestResponse, SandboxStatus, SessionStatus } from './core/types.js';
+export { main } from './cli/index.js';

package/dist/api.js

@@ -0,0 +1,30 @@
+// Programmatic API: `import { sandbox } from 'windows-development-sandbox'`. Same safety model as the CLI: the host only sends the
+// request kinds the guest daemon accepts, and everything coming back is validated data.
+import path from 'node:path';
+import { attachTerminal, execInSandbox, pickSession, pingSandbox, requestSession, restartSessions, waitForReady, waitForSession } from './host/channel.js';
+import { loadConfig } from './core/config.js';
+import { listSessions, readSandboxStatus } from './shared/rundir.js';
+import { isSandboxRunning } from './host/platform.js';
+import { expandPath, fail } from './core/util.js';
+export const sandbox = (options = {}) => {
+    const loaded = loadConfig(options.config);
+    const dataPath = path.join(expandPath(loaded.config.storage.root, loaded.base), 'data', loaded.config.storage.dataName);
+    const alive = isSandboxRunning;
+    // async: no sandbox is a rejected promise like every other failure, not a synchronous throw.
+    const ready = async () => (alive() ? waitForReady(dataPath, null, alive) : fail('No Windows Sandbox is running.', 'Start one first, e.g. sandbox claude --headless.'));
+    return {
+        isRunning: alive,
+        status: () => readSandboxStatus(dataPath),
+        ready,
+        sessions: () => listSessions(dataPath),
+        exec: async (command, o = {}) => execInSandbox(dataPath, command, o.cwd ?? (await ready()).guestWorkspace, o.timeoutSeconds ?? 600, alive),
+        startSession: async (o = {}) => {
+            const status = await ready();
+            return waitForSession(dataPath, requestSession(dataPath, o.harness ?? loaded.config.defaultHarness, o.args ?? [], o.cwd ?? status.guestWorkspace), alive);
+        },
+        restart: async (harness) => { await ready(); return restartSessions(dataPath, harness ?? null, alive); },
+        ping: async () => { await ready(); return pingSandbox(dataPath, alive); },
+        attach: async (sessionId) => { await ready(); return attachTerminal(pickSession(dataPath, sessionId)); },
+    };
+};
+export { main } from './cli/index.js';

package/dist/bin/agent-sandbox.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/agent-sandbox.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../cli/index.js';
+run(process.argv.slice(2));

package/dist/bin/claude-host.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/claude-host.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { run } from '../cli/index.js';
+const args = process.argv.slice(2);
+const personal = args.includes('--personal') ? ['--personal'] : [];
+run(['host-claude', ...personal, '--', ...args.filter((a) => a !== '--personal')]);

package/dist/bin/claude-sbx.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/claude-sbx.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../cli/index.js';
+run(process.argv.slice(2), { harness: 'claude' });

package/dist/bin/codex-sbx.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/codex-sbx.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../cli/index.js';
+run(process.argv.slice(2), { harness: 'codex' });

package/dist/bin/gemini-sbx.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/gemini-sbx.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../cli/index.js';
+run(process.argv.slice(2), { harness: 'gemini' });

package/dist/bin/sandbox.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/sandbox.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// sandbox / windows-development-sandbox: the menu with no arguments, any command, or `sandbox <agent>`.
+import { run } from '../cli/index.js';
+run(process.argv.slice(2));

package/dist/bin/sbx-hide.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/sbx-hide.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../cli/index.js';
+run(process.argv.slice(2), { command: 'hide' });

package/dist/bin/sbx-show.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/sbx-show.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../cli/index.js';
+run(process.argv.slice(2), { command: 'show' });

package/dist/cli/args.d.ts

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+export interface CliOptions {
+    command: string;
+    positionals: string[];
+    passthrough: string[];
+    config?: string;
+    workspace?: string;
+    harness?: string;
+    account?: string;
+    node?: string;
+    python?: string;
+    scripts: string[];
+    databases: string[];
+    headless?: boolean;
+    terminal: boolean;
+    newSession: boolean;
+    noAgent: boolean;
+    trustConfig: boolean;
+    noLocalConfig: boolean;
+    personal: boolean;
+    fromHost: boolean;
+    noRestart: boolean;
+    follow: boolean;
+    json: boolean;
+    yes: boolean;
+    timeout: number;
+    days: number;
+}
+/** Every command, its options and help text, from manifest.ts. Actions only record what was parsed. */
+export declare const buildProgram: (record: (name: string, cmd: Command) => void) => Command;
+/** Parses argv into the command name and options. Throws commander errors for unknown commands/options. */
+export declare const parseCli: (argv: string[], wrapper?: boolean) => CliOptions;