windows-development-sandbox 1.0.5 → 1.4.0

package/dist/core/schema/config.js

@@ -0,0 +1,75 @@
+// The user config and the smaller subset a project's .sandbox-config.json may change. Types are inferred from these
+// schemas, and the JSON Schema files in schemas/ are generated from them at build time.
+import _ from 'lodash';
+import { z } from 'zod';
+import { Name, SchemaRef, Strings, toggle } from './common.js';
+import { Databases } from './databases.js';
+import { Harness } from './harness.js';
+import { AgentCommands, Attach, ClaudeProfile, Secrets } from './profile.js';
+import { Audit, Downloads, Git, GuestWorkspace, Mapping, Network, Provisioning, Sandbox, WorkspaceFilter } from './sandbox.js';
+import { Toolchains } from './toolchains.js';
+import { Apps } from './apps.js';
+import { Projects } from './projects.js';
+export const Config = z.strictObject({
+    $schema: SchemaRef.optional(),
+    defaultHarness: Name.describe('Agent started by `sandbox launch` (sandbox claude always runs claude).'),
+    guestWorkspace: GuestWorkspace,
+    readOnly: z.boolean().describe('Map the workspace read-only.'),
+    workspaceFilter: WorkspaceFilter,
+    audit: Audit,
+    mappings: z.array(Mapping).describe('Extra folders from this PC.'),
+    sandbox: Sandbox,
+    storage: z.strictObject({
+        root: z.string().min(1).describe('Where everything is kept on this PC (tools, databases, logins, launches).'),
+        persistAgentState: z.boolean().describe('Keep agent logins and history between sandboxes.'),
+        dataName: Name.describe('Name of the persistent data set (C:\\AgentData) shared by all workspaces.'),
+        markSandboxFiles: z.boolean().describe('Programs and scripts (.exe, .ps1, .bat, .cmd, .msi, .lnk ...) that appear or change in your project while a sandbox runs get Windows\' "downloaded from the internet" mark, so SmartScreen and PowerShell ask before they run on this PC.'),
+        warnDataGb: z.number().min(0).describe('Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. sandbox data shows what takes the space.'),
+    }),
+    network: Network,
+    provisioning: Provisioning,
+    downloads: Downloads,
+    toolchains: Toolchains,
+    databases: Databases.describe('Databases running inside the sandbox. Data persists in C:\\AgentData\\databases; each one starts at boot.'),
+    attach: Attach,
+    agentCommands: AgentCommands,
+    secrets: Secrets,
+    personalization: toggle('Copy your desktop look (theme, accent, taskbar, wallpaper, ...) into the sandbox.'),
+    apps: Apps,
+    claudeProfile: ClaudeProfile,
+    harnesses: z.record(Name, Harness).describe('Agents that can run in the sandbox.'),
+    hooks: z.strictObject({ failFast: z.boolean().describe('Stop when a hook script fails.') }),
+    projects: Projects.describe('Several projects in one sandbox: folders of projects mapped at every start, and adding folders while it runs.'),
+}).refine((c) => c.harnesses[c.defaultHarness] !== undefined, { message: 'defaultHarness must be one of the configured harnesses', path: ['defaultHarness'] });
+/**
+ * What a project's .sandbox-config.json may change. A repo can ship this file, so it can NOT touch storage, agent
+ * executables, host folders for tools or Claude settings, or anything else outside this list.
+ */
+export const LocalOverrides = z.strictObject({
+    $schema: SchemaRef,
+    harness: Name.describe('Agent for this project.'),
+    guestWorkspace: GuestWorkspace,
+    readOnly: z.boolean().describe('Map this project read-only.'),
+    // A project may turn the filter on and keep more out, never let ignored files in.
+    workspaceFilter: WorkspaceFilter.pick({ enabled: true, exclude: true }).partial(),
+    mappings: z.array(Mapping).describe('Extra folders inside this project (relative to this file), e.g. a read-only data folder at another place in the sandbox.'),
+    scripts: Strings.describe('Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent.'),
+    // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
+    sandbox: Sandbox.omit({ cpuLimit: true, pageFileMb: true }).partial(),
+    // A project may block more (the LAN, hosts); it never opens hosts, ports, DNS or a proxy.
+    network: Network.pick({ blockPrivateRanges: true, blockHosts: true }).partial(),
+    provisioning: Provisioning.pick({ copyFromHost: true, fallbackToInstall: true, refresh: true }).extend({ git: Git.partial(), terminal: toggle('Windows Terminal as the sandbox window.').partial() }).partial(),
+    downloads: Downloads.partial(),
+    // Every toolchain setting, each one optional (a project usually only switches languages on or pins a version).
+    toolchains: z.strictObject({
+        ..._.mapValues(_.omit(Toolchains.shape, 'environment'), (shape) => shape.partial()),
+        environment: Toolchains.shape.environment,
+    }).partial(),
+    databases: z.strictObject(_.mapValues(Databases.shape, (shape) => shape.partial())).partial(),
+    attach: Attach.partial(),
+    personalization: toggle('Copy your desktop look into the sandbox.').partial(),
+    // Catalogue apps only (a vetted list): your own programs (apps.custom) download anything, so a repo cannot add them.
+    apps: Apps.pick({ install: true }).partial(),
+    claudeProfile: ClaudeProfile.pick({ enabled: true, overwrite: true, copyCredentials: true, syncHistory: true, syncClaudeMem: true }).partial(),
+    hooks: z.strictObject({ failFast: z.boolean() }).partial(),
+}).partial();

package/dist/core/schema/databases.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export declare const Port: z.ZodNumber;
+export declare const dbEnabled: (name: string) => z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const Databases: z.ZodObject<{
+    postgres: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        port: z.ZodNumber;
+    }, z.core.$strict>;
+    mysql: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        port: z.ZodNumber;
+    }, z.core.$strict>;
+    mongodb: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        port: z.ZodNumber;
+    }, z.core.$strict>;
+    redis: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        port: z.ZodNumber;
+    }, z.core.$strict>;
+    dynamodb: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        port: z.ZodNumber;
+        adminPort: z.ZodNumber;
+        admin: z.ZodBoolean;
+    }, z.core.$strict>;
+    sqlserver: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+    }, z.core.$strict>;
+}, z.core.$strict>;

package/dist/core/schema/databases.js

@@ -0,0 +1,35 @@
+// Databases that run inside the sandbox.
+import { z } from 'zod';
+import { Enabled } from './common.js';
+export const Port = z.number().int().min(1024).max(65535);
+export const dbEnabled = (name) => Enabled.describe(name + ': true, false, or "auto" = only when the project needs it (found from compose files, dependencies of every language, Prisma/ORM config and connection strings).');
+export const Databases = z.strictObject({
+    postgres: z.strictObject({
+        enabled: dbEnabled('PostgreSQL (with psql, pg_dump). User postgres, no password, localhost only'),
+        version: z.string().min(1).describe('"latest" or a major version such as "16". A compose file pinning postgres:<major> wins.'),
+        port: Port.describe('Port inside the sandbox.'),
+    }),
+    mysql: z.strictObject({
+        enabled: dbEnabled('MySQL-compatible database (MariaDB). User root, no password, localhost only'),
+        version: z.string().min(1).describe('"lts" (newest MariaDB LTS) or a MariaDB series such as "11.4".'),
+        port: Port.describe('Port inside the sandbox.'),
+    }),
+    mongodb: z.strictObject({
+        enabled: dbEnabled('MongoDB with mongosh, localhost only'),
+        version: z.string().min(1).describe('"latest" or a version prefix such as "8.0".'),
+        port: Port.describe('Port inside the sandbox.'),
+    }),
+    redis: z.strictObject({
+        enabled: dbEnabled('Redis (community Windows build), localhost only'),
+        port: Port.describe('Port inside the sandbox.'),
+    }),
+    dynamodb: z.strictObject({
+        enabled: dbEnabled('DynamoDB Local (Amazon\'s official emulator, on the Java toolchain) with dynamodb-admin, a web UI to browse and edit tables'),
+        port: Port.describe('DynamoDB endpoint port inside the sandbox (http://localhost:<port>).'),
+        adminPort: Port.describe('dynamodb-admin web UI port (open http://localhost:<adminPort> in the sandbox\'s browser).'),
+        admin: z.boolean().describe('Run dynamodb-admin next to DynamoDB Local.'),
+    }),
+    sqlserver: z.strictObject({
+        enabled: dbEnabled('SQL Server. It cannot run inside Windows Sandbox; when a project needs it you get a note to use Postgres or SQLite for local work'),
+    }),
+});

package/dist/core/schema/harness.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const Harness: z.ZodObject<{
+    hostExecutable: z.ZodOptional<z.ZodString>;
+    hostDir: z.ZodOptional<z.ZodString>;
+    npmPackage: z.ZodOptional<z.ZodString>;
+    npmBin: z.ZodOptional<z.ZodString>;
+    uvPackage: z.ZodOptional<z.ZodString>;
+    uvBin: z.ZodOptional<z.ZodString>;
+    arguments: z.ZodArray<z.ZodString>;
+    environment: z.ZodRecord<z.ZodString, z.ZodString>;
+    resumeArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;

package/dist/core/schema/harness.js

@@ -0,0 +1,17 @@
+// An agent (claude, codex, ...) the sandbox can run.
+import { z } from 'zod';
+import { Strings } from './common.js';
+export const Harness = z.strictObject({
+    hostExecutable: z.string().optional().describe('Executable copied from this PC when installed here (e.g. claude.exe).'),
+    hostDir: z.string().optional().describe('Folder of hostExecutable on this PC, or "auto" to search PATH and ~/.local/bin.'),
+    npmPackage: z.string().optional().describe('npm package installed inside the sandbox when there is no host copy.'),
+    npmBin: z.string().optional().describe('Command the npm package provides.'),
+    uvPackage: z.string().optional().describe('Python package installed with `uv tool install` inside the sandbox (e.g. aider-chat).'),
+    uvBin: z.string().optional().describe('Command the uv package provides.'),
+    arguments: Strings.describe('Arguments always passed to the agent.'),
+    environment: z.record(z.string(), z.string()).describe('Environment variables for the agent.'),
+    resumeArguments: Strings.optional().describe('Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation.'),
+})
+    .refine((h) => h.hostExecutable || h.npmPackage || h.uvPackage, 'needs hostExecutable, npmPackage or uvPackage')
+    .refine((h) => !h.uvPackage || h.uvBin, 'needs uvBin when uvPackage is set')
+    .refine((h) => !h.npmPackage || h.npmBin, 'needs npmBin when npmPackage is set');

package/dist/core/schema/json-schema.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+/** One readable line per problem: "sandbox.memoryMb: Too small: expected number to be >=2048". */
+export declare const describeIssues: (error: z.ZodError) => string[];
+/** JSON Schema documents for editors. The user config only lists what it changes, so nothing in it is required. */
+export declare const jsonSchemas: () => Record<string, object>;

package/dist/core/schema/json-schema.js

@@ -0,0 +1,25 @@
+// Readable validation messages and the JSON Schema documents generated from the settings schemas.
+import { z } from 'zod';
+import { Config, LocalOverrides } from './config.js';
+/** One readable line per problem: "sandbox.memoryMb: Too small: expected number to be >=2048". */
+export const describeIssues = (error) => error.issues.map((issue) => {
+    const at = issue.path.join('.');
+    if (issue.code === 'unrecognized_keys')
+        return issue.keys.map((k) => (at ? at + '.' : '') + k + ' is not allowed here').join('; ');
+    return (at || 'value') + ': ' + issue.message;
+});
+/** JSON Schema documents for editors. The user config only lists what it changes, so nothing in it is required. */
+export const jsonSchemas = () => {
+    const dropRequired = (node) => {
+        if (Array.isArray(node))
+            return node.map(dropRequired);
+        if (typeof node !== 'object' || node === null)
+            return node;
+        return Object.fromEntries(Object.entries(node).filter(([k]) => k !== 'required').map(([k, v]) => [k, dropRequired(v)]));
+    };
+    const toSchema = (schema, title) => ({ title, ...z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }) });
+    return {
+        'config.schema.json': dropRequired(toSchema(Config, 'windows-development-sandbox user config (~/.agent-sandbox/config.json)')),
+        'sandbox-config.schema.json': toSchema(LocalOverrides, 'windows-development-sandbox project config (.sandbox-config.json)'),
+    };
+};

package/dist/core/schema/profile.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export declare const Secrets: z.ZodObject<{
+    strip: z.ZodBoolean;
+    allow: z.ZodArray<z.ZodString>;
+    patterns: z.ZodArray<z.ZodString>;
+    warnFiles: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const Attach: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    reuseSession: z.ZodBoolean;
+    auto: z.ZodBoolean;
+    autoHide: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const AgentCommands: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    agents: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodArray<z.ZodString>]>;
+}, z.core.$strict>;
+export declare const ClaudeProfile: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    hostDir: z.ZodString;
+    include: z.ZodArray<z.ZodString>;
+    globalStateFile: z.ZodString;
+    copyCredentials: z.ZodBoolean;
+    overwrite: z.ZodBoolean;
+    syncHistory: z.ZodBoolean;
+    historyScope: z.ZodEnum<{
+        project: "project";
+        all: "all";
+    }>;
+    syncClaudeMem: z.ZodBoolean;
+    syncClaudeMemBack: z.ZodBoolean;
+}, z.core.$strict>;

package/dist/core/schema/profile.js

@@ -0,0 +1,31 @@
+// What is copied from this PC, and how the terminal attaches.
+import { z } from 'zod';
+import { Name, Strings } from './common.js';
+export const Secrets = z.strictObject({
+    strip: z.boolean().describe('Remove credentials from everything copied into the sandbox (your Claude settings.json "env" and credential helpers, MCP servers\' env, headers and arguments): AWS, Azure, Google Cloud, Cloudflare, hosting, CI, registries, payment, AI API keys, database URLs, anything named *_TOKEN / *_SECRET / *PASSWORD* / *_KEY or *PROD*, and values that look like keys.'),
+    allow: Strings.describe('Variable names that may go in anyway; * matches anything, e.g. ["AWS_REGION", "AWS_PROFILE", "MY_APP_*"].'),
+    patterns: Strings.describe('More variable names to treat as secrets; * matches anything, e.g. ["ACME_*", "*_INTERNAL_URL"].'),
+    warnFiles: z.boolean().describe('Warn at launch about files in the workspace that usually hold secrets (.env, *.pem, credentials.json, ...). The agent CAN read them: Windows Sandbox maps the whole folder.'),
+});
+export const Attach = z.strictObject({
+    enabled: z.boolean().describe('Allow sandbox claude --terminal / sandbox attach from this PC.'),
+    reuseSession: z.boolean().describe('sandbox claude -t in a running sandbox reattaches to this folder\'s session when no terminal on this PC is attached to it (--new always starts another).'),
+    auto: z.boolean().describe('Starting an agent attaches this terminal automatically, as if you passed -t (only in an interactive terminal).'),
+    autoHide: z.boolean().describe('Hide the Windows Sandbox window whenever this terminal attaches; it keeps running (sandbox show brings it back).'),
+});
+export const AgentCommands = z.strictObject({
+    enabled: z.boolean().describe('(Beta) Typing an agent\'s own command on this PC (claude, codex, ...) starts it in a hidden sandbox for the folder you are in and attaches that terminal. Adds one folder to the start of YOUR PATH; off removes it. SANDBOX_AGENT_DIRECT=1 runs the real agent instead.'),
+    agents: z.union([z.literal('auto'), z.array(Name)]).describe('"auto" = every agent installed on this PC, or a list of agent names, e.g. ["claude", "codex"].'),
+});
+export const ClaudeProfile = z.strictObject({
+    enabled: z.boolean().describe('Copy selected Claude settings from this PC into the sandbox.'),
+    hostDir: z.string().describe('Your Claude folder, or "auto" (~/.claude or CLAUDE_CONFIG_DIR).'),
+    include: z.array(z.string().regex(/^[A-Za-z0-9._-]+$/)).describe('Files and folders copied from it.'),
+    globalStateFile: z.string().describe('Your .claude.json, or "auto". Empty string = do not copy.'),
+    copyCredentials: z.boolean().describe('Copy your Claude LOGIN into the sandbox. Prefer sandbox account instead.'),
+    overwrite: z.boolean().describe('Refresh these settings from this PC on every launch.'),
+    syncHistory: z.boolean().describe('Bring conversation history in, and sync new history back (path-translated).'),
+    historyScope: z.enum(['project', 'all']).describe('Which history comes in: "project" = only the projects in this sandbox (other projects\' conversations, file backups and prompts stay on this PC), "all" = everything. Only this sandbox\'s projects ever sync back.'),
+    syncClaudeMem: z.boolean().describe('Bring claude-mem data into the sandbox (its settings and backups stay on this PC).'),
+    syncClaudeMemBack: z.boolean().describe('Also copy claude-mem\'s database back to this PC when the sandbox closes. Off by default: what is in it is loaded into every Claude session on this PC, so a compromised agent could plant instructions there.'),
+});

package/dist/core/schema/projects.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const Projects: z.ZodObject<{
+    all: z.ZodBoolean;
+    exclude: z.ZodArray<z.ZodString>;
+    roots: z.ZodArray<z.ZodString>;
+    askToAddRoot: z.ZodBoolean;
+    declinedRoots: z.ZodArray<z.ZodString>;
+    wsbShare: z.ZodBoolean;
+}, z.core.$strict>;

package/dist/core/schema/projects.js

@@ -0,0 +1,11 @@
+// Several projects in one running sandbox. User config only: these settings map folders of this PC into the sandbox,
+// so a project's .sandbox-config.json can never set them (LocalOverrides has no `projects`).
+import { z } from 'zod';
+export const Projects = z.strictObject({
+    all: z.boolean().describe('Map every project you have started before (and every folder in your roots) at every start, except those in exclude, so all of them open in the running sandbox without a restart. Every agent in the sandbox can then see all of them. Each one is still only set up when you first use it.'),
+    exclude: z.array(z.string().min(1)).describe('Projects left out when "all" is on (folders on this PC).'),
+    roots: z.array(z.string().min(1)).describe('Folders whose subfolders are your projects (e.g. "F:\\\\Code"), mapped read/write at every start. Any project inside one, including ones you create later, opens in the running sandbox at once, without a restart. Every agent in the sandbox can see all of them.'),
+    askToAddRoot: z.boolean().describe('When you start a project whose parent folder is not a root yet, ask once whether to add it.'),
+    declinedRoots: z.array(z.string().min(1)).describe('Parent folders you said no to (not asked again).'),
+    wsbShare: z.boolean().describe('On Windows 11 24H2+ with the Windows Sandbox command line (wsb), add other folders to the running sandbox with `wsb share` (untested). Otherwise starting a project outside every root offers a restart.'),
+});

package/dist/core/schema/sandbox.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+export declare const GuestWorkspace: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"mirror">, z.ZodString]>;
+export declare const Mapping: z.ZodObject<{
+    host: z.ZodString;
+    guest: z.ZodString;
+    readOnly: z.ZodBoolean;
+    optional: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const Sandbox: z.ZodObject<{
+    memoryMb: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
+    maxMemoryMb: z.ZodNumber;
+    maxMemoryPercent: z.ZodNumber;
+    cpuLimit: z.ZodUnion<readonly [z.ZodLiteral<"none">, z.ZodNumber]>;
+    pageFileMb: z.ZodNumber;
+    reserveHostMb: z.ZodNumber;
+    vGpu: z.ZodBoolean;
+    networking: z.ZodBoolean;
+    clipboard: z.ZodBoolean;
+    audioInput: z.ZodBoolean;
+    videoInput: z.ZodBoolean;
+    printerRedirection: z.ZodBoolean;
+    protectedClient: z.ZodBoolean;
+    headless: z.ZodBoolean;
+    keepAwake: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const Network: z.ZodObject<{
+    blockPrivateRanges: z.ZodBoolean;
+    allowOnly: z.ZodArray<z.ZodString>;
+    blockHosts: z.ZodArray<z.ZodString>;
+    forwardPorts: z.ZodArray<z.ZodObject<{
+        pc: z.ZodNumber;
+        sandbox: z.ZodNumber;
+    }, z.core.$strict>>;
+    dns: z.ZodArray<z.ZodString>;
+    proxy: z.ZodString;
+}, z.core.$strict>;
+export declare const Audit: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    days: z.ZodNumber;
+    maxMb: z.ZodNumber;
+    processes: z.ZodBoolean;
+    files: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const WorkspaceFilter: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    exclude: z.ZodArray<z.ZodString>;
+    include: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const Git: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    access: z.ZodEnum<{
+        readonly: "readonly";
+        full: "full";
+        none: "none";
+    }>;
+}, z.core.$strict>;
+export declare const Provisioning: z.ZodObject<{
+    copyFromHost: z.ZodBoolean;
+    fallbackToInstall: z.ZodBoolean;
+    refresh: z.ZodBoolean;
+    git: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        access: z.ZodEnum<{
+            readonly: "readonly";
+            full: "full";
+            none: "none";
+        }>;
+    }, z.core.$strict>;
+    terminal: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>;
+    conpty: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const Downloads: z.ZodObject<{
+    requireChecksum: z.ZodBoolean;
+}, z.core.$strict>;

package/dist/core/schema/sandbox.js

@@ -0,0 +1,64 @@
+// The sandbox machine, folders mapped into it, and what is provisioned (Git, terminal).
+import { z } from 'zod';
+import { GitAccess, GuestPath, toggle } from './common.js';
+export const GuestWorkspace = z.union([z.literal('auto'), z.literal('mirror'), GuestPath]).describe('Where the workspace appears inside the sandbox. "auto" = C:\\Workspace\\<folder name>. "mirror" = the same path as on this PC, so absolute paths in configs and build caches match (another drive letter such as F: is a subst drive onto C:\\Mirror\\F); paths the sandbox reserves (C:\\Users\\..., C:\\Program Files\\...) fall back to "auto".');
+export const Mapping = z.strictObject({
+    host: z.string().min(1).describe('Folder on this PC (relative paths are relative to the config file).'),
+    guest: GuestPath.describe('Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game: mapped to C:\\Mirror\\F\\... and shown as F: (subst) at boot.'),
+    readOnly: z.boolean().describe('true = the agent can only read it.'),
+    optional: z.boolean().optional().describe('true = skip it quietly when the host folder does not exist.'),
+});
+export const Sandbox = z.strictObject({
+    memoryMb: z.union([z.literal('auto'), z.number().int().min(2048)]).describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb.'),
+    maxMemoryMb: z.number().int().positive().describe('Upper limit for memoryMb "auto".'),
+    maxMemoryPercent: z.number().int().min(10).max(100).describe('memoryMb "auto" never takes more than this share of this PC\'s total RAM (percent).'),
+    cpuLimit: z.union([z.literal('none'), z.number().int().min(5).max(100)]).describe('Most of this PC\'s CPU the sandbox may use, in percent (5-100), e.g. 50 keeps half free for you; "none" = no cap (Windows Sandbox would take every processor). Covers everything this tool starts in the sandbox (agents, installs, builds, its terminal).'),
+    pageFileMb: z.number().int().min(0).max(262144).describe('Size of the sandbox\'s paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with "The paging file is too small", and Windows grows the file under load. 0 = leave Windows\' own.'),
+    reserveHostMb: z.number().int().nonnegative().describe('RAM always left for this PC when memoryMb is "auto".'),
+    vGpu: z.boolean().describe('Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface.'),
+    networking: z.boolean().describe('Internet access. false is the only hard network isolation Windows Sandbox offers.'),
+    clipboard: z.boolean().describe('Shared clipboard between this PC and the sandbox.'),
+    audioInput: z.boolean().describe('Microphone access.'),
+    videoInput: z.boolean().describe('Camera access.'),
+    printerRedirection: z.boolean().describe('Printers from this PC.'),
+    protectedClient: z.boolean().describe('Run the sandbox window in Protected Client mode (recommended).'),
+    headless: z.boolean().describe('Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends.'),
+    keepAwake: z.boolean().describe('Keep this PC from sleeping while a sandbox runs, so agents left working overnight keep going (the screen may still turn off; closing a laptop lid still sleeps it).'),
+});
+const Port = z.number().int().min(1).max(65535);
+const HostEntry = z.string().max(253).regex(/^(@developer|(\*\.)?([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+)$/, 'a host name like example.com, *.example.com, or @developer');
+export const Network = z.strictObject({
+    blockPrivateRanges: z.boolean().describe('Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox.'),
+    allowOnly: z.array(HostEntry).describe('Only these hosts can be reached once the sandbox is set up (tools still download first). *.example.com covers its subdomains; @developer adds package registries, GitHub, toolchain downloads and the AI providers. Programs go through a proxy in the sandbox (HTTP_PROXY); anything else is blocked by its firewall. Empty = no limit.'),
+    blockHosts: z.array(z.string().max(253).regex(/^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/, 'a host name like telemetry.example.com')).describe('Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox\'s hosts file sends them nowhere).'),
+    forwardPorts: z.array(z.strictObject({
+        pc: Port.describe('The port on this PC (localhost only).'),
+        sandbox: Port.describe('The port inside the sandbox (a server there may listen on localhost only).'),
+    })).describe('Reach servers in the sandbox from this PC: http://localhost:<pc> here goes to <sandbox> inside, while it runs. Nothing else on your network can use them.'),
+    dns: z.array(z.string().regex(/^\d{1,3}(\.\d{1,3}){3}$/, 'an IPv4 address like 1.1.1.1')).describe('DNS servers for the sandbox instead of your network\'s, e.g. 1.1.1.1 and 9.9.9.9.'),
+    proxy: z.string().regex(/^(https?:\/\/[^\s]+)?$/, 'http://host:port').describe('An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none.'),
+});
+export const Audit = z.strictObject({
+    enabled: z.boolean().describe('Keep an audit log on this PC of what happened in your sandboxes: programs started (with their command lines), files changed in the project, sessions, and what the repo guard caught. The sandbox cannot change it. Read it with sandbox audit.'),
+    days: z.number().int().min(1).max(365).describe('Days the audit log is kept.'),
+    maxMb: z.number().int().min(5).max(5000).describe('Most space the audit log may take, in MB (older days go first). Days before today are compressed.'),
+    processes: z.boolean().describe('Record every program started in the sandbox with its command line (Windows process auditing; repeated runs are counted, not listed).'),
+    files: z.boolean().describe('Record the files changed in the project while the sandbox runs.'),
+});
+export const WorkspaceFilter = z.strictObject({
+    enabled: z.boolean().describe('Keep what your .gitignore lists (.env files, node_modules, build output ...) out of the sandbox. The sandbox works on a copy of the project without those files, kept in step with it both ways within about a second; what it creates that is ignored (its own node_modules, builds) stays in the sandbox. Git works as usual. Off = the project folder itself is mapped.'),
+    exclude: z.array(z.string().max(500)).describe('Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/.'),
+    include: z.array(z.string().max(500)).describe('Let these in although .gitignore lists them, e.g. .env.example, data/fixtures/.'),
+});
+export const Git = z.strictObject({ enabled: z.boolean().describe('Provide Git for Windows (and Git Bash, which Claude Code needs).'), access: GitAccess });
+export const Provisioning = z.strictObject({
+    copyFromHost: z.boolean().describe('Copy Node, Git, nvm and the agent from this PC when they are installed here.'),
+    fallbackToInstall: z.boolean().describe('Download anything that cannot be copied from this PC.'),
+    refresh: z.boolean().describe('Re-copy / re-download everything on the next launch.'),
+    git: Git,
+    terminal: toggle('Windows Terminal as the sandbox window (downloaded once).'),
+    conpty: toggle('Agent sessions use Microsoft\'s newer pseudo console (conpty.dll, downloaded once) instead of the one built into Windows: no garbled screen after resizing, real scrollback for the mouse wheel. Off = the one built into Windows.'),
+});
+export const Downloads = z.strictObject({
+    requireChecksum: z.boolean().describe('Refuse any toolchain, database or tool download that has no published checksum (SHA-256/SHA-512) to verify it against. false = allow those, as before. Downloads that do have a published checksum are always verified. A project\'s .sandbox-config.json can only turn this on.'),
+});

package/dist/core/schema/toolchains.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+export declare const Toolchains: z.ZodObject<{
+    node: z.ZodObject<{
+        version: z.ZodString;
+        extraVersions: z.ZodArray<z.ZodString>;
+        corepack: z.ZodBoolean;
+        volta: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        globalPackages: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    python: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        python2: z.ZodBoolean;
+        pyenv: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        tools: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    rust: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        toolchain: z.ZodString;
+        host: z.ZodString;
+        components: z.ZodArray<z.ZodString>;
+        targets: z.ZodArray<z.ZodString>;
+        crates: z.ZodArray<z.ZodString>;
+        targetDir: z.ZodString;
+    }, z.core.$strict>;
+    msvc: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        acceptLicense: z.ZodBoolean;
+        msvcVersion: z.ZodString;
+        sdkVersion: z.ZodString;
+    }, z.core.$strict>;
+    cpp: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        flexBison: z.ZodBoolean;
+    }, z.core.$strict>;
+    dotnet: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        channels: z.ZodArray<z.ZodString>;
+        tools: z.ZodArray<z.ZodString>;
+        workloads: z.ZodArray<z.ZodString>;
+        frameworkTargets: z.ZodArray<z.ZodString>;
+        netfx35: z.ZodBoolean;
+    }, z.core.$strict>;
+    go: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        tools: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    java: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        maven: z.ZodBoolean;
+        gradle: z.ZodBoolean;
+    }, z.core.$strict>;
+    ruby: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        gems: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    php: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        version: z.ZodString;
+        composer: z.ZodBoolean;
+    }, z.core.$strict>;
+    deno: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+    }, z.core.$strict>;
+    pwsh: z.ZodObject<{
+        enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+    }, z.core.$strict>;
+    cli: z.ZodObject<{
+        gh: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        zstd: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+        openssl: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+    }, z.core.$strict>;
+    bun: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>;
+    uv: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>;
+    vcRuntime: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>;
+    mesa: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        vulkan: z.ZodBoolean;
+    }, z.core.$strict>;
+    vscode: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        setup: z.ZodBoolean;
+        recommended: z.ZodBoolean;
+        extensions: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    environment: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;