windows-development-sandbox 1.7.0 → 1.10.0

package/schemas/config.schema.json

@@ -120,6 +120,14 @@
     "sandbox": {
       "type": "object",
       "properties": {
+        "engine": {
+          "type": "string",
+          "enum": [
+            "windows-sandbox",
+            "hcs"
+          ],
+          "description": "(alpha) What runs the sandbox. \"windows-sandbox\" = Windows Sandbox (the default: desktop, Windows Terminal, GPU, clipboard, audio, printers). \"hcs\" = a headless Hyper-V isolated Server Core container for agents (no desktop, GPU or clipboard); it needs Windows features and an image on this PC (sandbox engine check hcs lists what is missing), and starting it is not enabled yet in this alpha. sandbox engine shows what each engine can do. Yours only: a project file (.sandbox-config.json) cannot set it."
+        },
         "memoryMb": {
           "anyOf": [
             {
@@ -170,11 +178,33 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 9007199254740991,
-          "description": "RAM always left for this PC when memoryMb is \"auto\"."
+          "description": "Memory always left for this PC when memoryMb is \"auto\": the sandbox gets at most (free RAM, and RAM plus paging file still unused) minus this."
+        },
+        "agentMemoryHeadroomMb": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "auto"
+            },
+            {
+              "type": "string",
+              "const": "none"
+            },
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            }
+          ],
+          "description": "Memory kept out of the agents reach inside the sandbox, in MB: everything the agents start (their builds, tests, tools) together may use at most the sandbox memory minus this; a runaway parallel build then gets out-of-memory errors in its own session instead of freezing or crashing the whole sandbox. \"auto\" = the larger of 2048 MB and 10 % of the sandbox memory; \"none\" = no limit. Yours only: a project file cannot change it."
+        },
+        "pressureResponse": {
+          "type": "boolean",
+          "description": "When the sandbox (or this PC) runs low on memory, slow the heaviest build programs down (lower priority) and, if that is not enough, pause the biggest compiler for a few seconds at a time, so heavy parallel builds slow down instead of closing the sandbox. Never touches the agents themselves. Yours only: a project file cannot change it."
         },
         "vGpu": {
           "type": "boolean",
-          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface."
+          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface. The sandbox then uses this PC's graphics card, and with some graphics drivers heavy use can freeze the whole PC: turn it on only when a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it)."
         },
         "networking": {
           "type": "boolean",
@@ -182,7 +212,7 @@
         },
         "clipboard": {
           "type": "boolean",
-          "description": "Shared clipboard between this PC and the sandbox."
+          "description": "Shared clipboard between this PC and the sandbox. Also lets an agent's copy (in sandbox attach) reach this PC's clipboard."
         },
         "audioInput": {
           "type": "boolean",
@@ -242,6 +272,20 @@
           "type": "boolean",
           "description": "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."
         },
+        "contained": {
+          "type": "string",
+          "enum": [
+            "off",
+            "vhdx"
+          ],
+          "description": "(beta) Keep the sandbox tools, state and logs inside one disk image file (vhdx) instead of loose folders, so scanning programs on this PC see one file. Not yet tried on a real PC. Turn it on with sandbox storage contained on (it moves your files and asks first); Windows asks for permission to mount the image when a sandbox starts. \"off\" = loose folders, as always. Yours only: a project file (.sandbox-config.json) cannot set it."
+        },
+        "containedMaxGb": {
+          "type": "integer",
+          "minimum": 8,
+          "maximum": 4096,
+          "description": "(beta) Largest size, in GB, the disk image of storage.contained may grow to."
+        },
         "warnDataGb": {
           "type": "number",
           "minimum": 0,
@@ -318,15 +362,16 @@
       "properties": {
         "enabled": {
           "type": "boolean",
-          "description": "Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (sandbox vpn login). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."
+          "description": "(Alpha: not yet tried on a real PC) Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (sandbox vpn login). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."
         },
         "provider": {
           "type": "string",
           "enum": [
             "nordvpn",
-            "openvpn-file"
+            "openvpn-file",
+            "wireguard-file"
           ],
-          "description": "nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile)."
+          "description": "nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile). wireguard-file: your own WireGuard .conf (configFile), e.g. from your company."
         },
         "protocol": {
           "type": "string",
@@ -343,7 +388,7 @@
         },
         "configFile": {
           "type": "string",
-          "description": "openvpn-file: the .ovpn file on this PC (its certificates inside it). Files that run programs (script-security, up, down, plugin ...) are refused. A project's file can never set this."
+          "description": "openvpn-file / wireguard-file: the .ovpn or .conf file on this PC (an .ovpn has its certificates inside it). Files that run programs (script-security, up, down, plugin, PostUp ...) are refused. A WireGuard file holds your private key: it is read when a sandbox starts and handed over in a one-shot file. A project's file can never set this."
         },
         "killSwitch": {
           "type": "boolean",
@@ -1191,13 +1236,17 @@
       "properties": {
         "enabled": {
           "type": "boolean",
-          "description": "(Beta) Allow the web UI: your sandbox sessions in a browser on this PC. Off by default, and nothing starts it by itself yet: sandbox web start works either way and runs it until sandbox web stop (or a restart of the PC)."
+          "description": "(Beta) The web UI: your sandbox sessions in a browser on this PC (http://127.0.0.1:<port>, this PC only). On: every sandbox start also starts it in the background (it keeps running until sandbox web stop or a restart of the PC). Off: only sandbox web start runs it. Open it signed in with sandbox web open."
         },
         "port": {
           "type": "integer",
           "minimum": 1024,
           "maximum": 65535,
           "description": "Port of the web UI on 127.0.0.1 (this PC only). Pick another when it is taken."
+        },
+        "openOnLaunch": {
+          "type": "boolean",
+          "description": "(Beta) With the web UI on: open it in your browser, already signed in, every time a sandbox starts."
         }
       },
       "additionalProperties": false
@@ -1576,6 +1625,15 @@
               "pattern": "^(?!.*(^|[\\\\/])\\.\\.([\\\\/]|$))[A-Za-z0-9._ -]+([\\\\/][A-Za-z0-9._ -]+)*$"
             }
           },
+          "bootReset": {
+            "description": "Files and folders below the agent's own state folder (state\\<agent>) that only work on the machine that wrote them (keys sealed with Windows DPAPI, local accounts it created). Every sandbox is a new machine, so they are deleted at each boot and the agent sets them up again.",
+            "maxItems": 32,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(?!.*(^|[\\\\/])\\.\\.([\\\\/]|$))[A-Za-z0-9._ -]+([\\\\/][A-Za-z0-9._ -]+)*$"
+            }
+          },
           "resumeArguments": {
             "description": "Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation.",
             "type": "array",

package/schemas/sandbox-config.schema.json

@@ -123,11 +123,11 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 9007199254740991,
-          "description": "RAM always left for this PC when memoryMb is \"auto\"."
+          "description": "Memory always left for this PC when memoryMb is \"auto\": the sandbox gets at most (free RAM, and RAM plus paging file still unused) minus this."
         },
         "vGpu": {
           "type": "boolean",
-          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface."
+          "description": "Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface. The sandbox then uses this PC's graphics card, and with some graphics drivers heavy use can freeze the whole PC: turn it on only when a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it)."
         },
         "networking": {
           "type": "boolean",
@@ -135,7 +135,7 @@
         },
         "clipboard": {
           "type": "boolean",
-          "description": "Shared clipboard between this PC and the sandbox."
+          "description": "Shared clipboard between this PC and the sandbox. Also lets an agent's copy (in sandbox attach) reach this PC's clipboard."
         },
         "audioInput": {
           "type": "boolean",

package/dist/cli/commands/sessions/control.d.ts

@@ -1,4 +0,0 @@
-import { type Context } from '../context.js';
-/** Restarts this folder's project's sessions (--all: every session). */
-export declare function restart(ctx: Context): Promise<number>;
-export declare function stop(asked: Context): Promise<number>;

package/dist/cli/commands/sessions/control.js

@@ -1,66 +0,0 @@
-import path from 'node:path';
-import { askYesNo } from '../../../core/prompt.js';
-import { fail, safeText } from '../../../core/util/index.js';
-import { SandboxChannel } from '../../../host/channel/index.js';
-import { runningOwner } from '../../../host/sharing/index.js';
-import { useSharedSandbox } from '../shared-use.js';
-import { requireOnPc, requireRunning } from '../context.js';
-import { working, c } from '../../output/index.js';
-import { SandboxService, SessionsService } from '../../services/index.js';
-/** Restarts this folder's project's sessions (--all: every session). */
-export async function restart(ctx) {
-    requireOnPc('restart');
-    requireRunning();
-    await useSharedSandbox(ctx, { kind: 'owner-only', what: 'restart the agents' });
-    const service = new SessionsService(ctx);
-    const scope = service.restartScope(Boolean(ctx.options.all));
-    if (scope.notAProject)
-        console.log(c.dim(scope.folder + ' is not a project of the running sandbox: restarting every session.'));
-    console.log(safeText(await working('Restarting the agents' + (scope.guest ? ' of ' + scope.projectName : ''), () => service.restart(ctx.options.harness ?? null, scope.guest))));
-    return 0;
-}
-/**
- * Stopping ends every project's sessions: other projects' sessions need a yes (or --yes). A script must never end them
- * by accident, so without a terminal to ask in it fails.
- */
-async function othersMayEnd(ctx, others) {
-    if (!others.length || ctx.options.yes)
-        return true;
-    const interactive = process.stdin.isTTY && process.stdout.isTTY;
-    if (!interactive)
-        fail(others.length + ' of these sessions belong to other projects, so the sandbox was not stopped.', 'Stop it anyway with: sandbox stop --yes');
-    return askYesNo(others.length + ' of them belong to other projects. Stop the whole sandbox?');
-}
-export async function stop(asked) {
-    requireOnPc('stop');
-    if (!new SandboxService(asked).isRunning()) {
-        console.log('No Windows Sandbox is running.');
-        return 0;
-    }
-    // Another user's sandbox: only when shared, and only after typing their name (--yes in scripts).
-    let ctx = asked;
-    if (runningOwner().kind !== 'mine') {
-        ctx = await useSharedSandbox(asked, (shared) => ({
-            kind: 'stop',
-            sessions: new SandboxChannel(shared.dataPath).currentSessions().length,
-        }));
-    }
-    const service = new SandboxService(ctx);
-    // Stopping ends every project's sessions, not just this folder's: say which, and ask when others would end too.
-    const { sandbox, running, others } = service.stopPlan();
-    if (running.length)
-        console.log('Stopping ends ' +
-            running.length +
-            ' session(s): ' +
-            running
-                .map((s) => safeText(s.harness) + ' in ' + safeText(s.project ?? path.win32.basename(s.cwd)))
-                .join(', ') +
-            '.');
-    if (!(await othersMayEnd(ctx, others))) {
-        console.log('Nothing changed.');
-        return 1;
-    }
-    await working('Asking the sandbox to shut down', () => service.shutdown(sandbox));
-    console.log('Sandbox is shutting down; history and claude-mem sync back when it closes.');
-    return 0;
-}

package/dist/cli/commands/sessions/list.d.ts

@@ -1,2 +0,0 @@
-import { type Context } from '../context.js';
-export declare function sessions(asked: Context): Promise<number>;

package/dist/cli/commands/sessions/list.js

@@ -1,48 +0,0 @@
-import _ from 'lodash';
-import { safeText } from '../../../core/util/index.js';
-import { printJson, table, ago, c, shortenMiddle, termWidth } from '../../output/index.js';
-import { SessionsService, viewerText } from '../../services/index.js';
-import { lookAtSandbox } from '../shared-use.js';
-export async function sessions(asked) {
-    // Another user's sandbox: shared, its sessions are listed from their folders; not shared, only whose it is.
-    const view = lookAtSandbox(asked);
-    const ctx = view.ctx;
-    if (view.limited) {
-        if (!printJson(ctx, []))
-            console.log(view.line);
-        return 0;
-    }
-    if (view.line && !ctx.options.json)
-        console.log(c.bold(view.line));
-    const service = new SessionsService(ctx);
-    const list = await service.list();
-    if (printJson(ctx, list.map((s) => _.omit(s, 'attach'))))
-        return 0;
-    if (list.length === 0) {
-        console.log('No sessions. Start one with: sandbox claude');
-        return 0;
-    }
-    // Harness, cwd and times are written by the sandbox.
-    const wide = ctx.options.wide;
-    const folderWidth = Math.max(16, termWidth() - 80);
-    table([
-        ['', 'ID', 'AGENT', 'PROJECT', 'STATE', 'ATTACHED', ...(wide ? ['FOLDER'] : []), 'STARTED'],
-        ...service
-            .ordered(list)
-            .map((s) => [
-            s.here ? '*' : '',
-            s.id,
-            safeText(s.harness),
-            safeText(s.projectName ?? '-'),
-            s.phase + (s.exitCode !== undefined ? ' (' + s.exitCode + ')' : ''),
-            viewerText(s.viewers),
-            ...(wide ? [shortenMiddle(safeText(s.cwd), folderWidth)] : []),
-            ago(s.startedAt),
-        ]),
-    ]);
-    if (list.some((s) => s.here))
-        console.log(c.dim('* = the project of this folder'));
-    if (!wide)
-        console.log(c.dim('Folders: sandbox sessions --wide'));
-    return 0;
-}

package/dist/cli/commands/sessions/status.d.ts

@@ -1,4 +0,0 @@
-import type { Context } from '../context.js';
-/** "pong (2 session(s) running)" from the helper in the sandbox, in plain words. */
-export declare function helperText(answer: string): string;
-export declare function status(asked: Context): Promise<number>;

package/dist/cli/commands/sessions/status.js

@@ -1,114 +0,0 @@
-import { safeText } from '../../../core/util/index.js';
-import { printJson, table, ago, c, shortenMiddle, termWidth } from '../../output/index.js';
-import { SandboxService } from '../../services/index.js';
-import { lookAtSandbox } from '../shared-use.js';
-const MECHANISM_TEXT = {
-    launch: 'started from here',
-    root: 'in a project root',
-    boot: 'mapped at start',
-};
-function mechanismText(mechanism) {
-    return mechanism in MECHANISM_TEXT ? MECHANISM_TEXT[mechanism] : 'wsb share';
-}
-function printProject(p) {
-    console.log((p.here ? '* ' : '  ') +
-        c.bold(p.name) +
-        '  ' +
-        p.host +
-        '  ->  ' +
-        p.guest +
-        c.dim('  (' + mechanismText(p.mechanism) + ')'));
-    console.log('      setup: ' +
-        p.setup.phase +
-        (p.setup.phase === 'ready' ? '' : ' - ' + shortenMiddle(p.setup.message, termWidth() - 20)));
-    if (p.databases.length)
-        console.log('      databases: ' + p.databases.map((d) => d.database + ' :' + d.port + ' ' + d.state).join(', '));
-    for (const s of p.sessions)
-        console.log('      session ' + s.id + '  ' + s.harness + '  ' + s.viewers + '  ' + ago(s.started));
-    for (const f of p.repoGuard)
-        console.log('      ' + c.yellow('guard: ' + f));
-}
-/** "pong (2 session(s) running)" from the helper in the sandbox, in plain words. */
-export function helperText(answer) {
-    const sessions = /^pong \((\d+) session/.exec(answer);
-    if (!sessions)
-        return answer === '-' ? '-' : safeText(answer);
-    return 'responding, ' + sessions[1] + (sessions[1] === '1' ? ' session' : ' sessions') + ' running';
-}
-export async function status(asked) {
-    // Another user's sandbox: shared, it is shown from their folders; not shared, only whose it is.
-    const view = lookAtSandbox(asked);
-    const ctx = view.ctx;
-    if (view.limited) {
-        const owner = view.owner;
-        const user = owner?.kind === 'other' ? owner.user : null;
-        if (!printJson(ctx, { sandbox: { running: true, shared: false, startedBy: user } }))
-            console.log(view.line);
-        return 0;
-    }
-    const report = await new SandboxService(ctx).status();
-    const { startedAt, ...state } = report.sandbox;
-    const info = {
-        // Same keys and order as the service's state, with the start time shown as an uptime.
-        sandbox: {
-            ...(ctx.borrowed ? { startedBy: ctx.borrowed.user, shared: true } : {}),
-            running: state.running,
-            phase: state.phase,
-            message: state.message,
-            headless: state.headless,
-            uptime: state.running && startedAt ? ago(startedAt).replace(' ago', '') : null,
-            daemon: state.daemon,
-            account: state.account,
-            syncWatcher: state.syncWatcher,
-        },
-        here: report.here,
-        roots: report.roots,
-        projects: report.projects,
-        otherSessions: report.otherSessions,
-        repoGuard: report.repoGuard,
-    };
-    if (printJson(ctx, info))
-        return 0;
-    const sb = info.sandbox;
-    if (view.line)
-        console.log(c.bold(view.line) + c.dim('. Its window is on their desktop; use its agents here.'));
-    table([
-        ...(ctx.borrowed ? [['Started by', safeText(ctx.borrowed.user)]] : []),
-        ['Running', sb.running ? 'yes' : 'no'],
-        ...(sb.running
-            ? [
-                ['Phase', safeText(sb.phase ?? '-')],
-                ['Message', safeText(sb.message ?? '-')],
-                ['Window', sb.headless ? 'hidden (sandbox show opens it)' : 'shown'],
-                ['Uptime', sb.uptime ?? '-'],
-                ['Helper', helperText(sb.daemon)],
-            ]
-            : []),
-        ['Account', sb.account ? safeText(sb.account) : 'none selected (sandbox account use)'],
-        ['Background sync', sb.syncWatcher ? 'on' : 'off'],
-    ]);
-    if (!state.running)
-        return 0;
-    console.log('\n' + c.bold('Projects'));
-    for (const p of info.projects)
-        printProject(p);
-    for (const r of info.roots)
-        console.log('  root  ' + r.host + '  ->  ' + r.guest + c.dim('  (every project in it opens without a restart)'));
-    console.log(c.dim(info.projects.some((p) => p.here)
-        ? '* = the project of this folder'
-        : info.here.folder + ' is not in this sandbox (start it here: sandbox claude)'));
-    for (const s of info.otherSessions)
-        console.log('  session ' + s.id + '  ' + s.harness + '  ' + s.cwd);
-    const findings = info.repoGuard.findings;
-    console.log('\n' +
-        c.bold('Repo guard') +
-        '  ' +
-        info.repoGuard.guarded +
-        ' folder(s) guarded; ' +
-        (findings.length
-            ? c.yellow(findings.length + ' change(s) neutralised:')
-            : 'nothing from the sandbox needed neutralising'));
-    for (const f of findings.slice(-10))
-        console.log('  ' + c.yellow(safeText(f)));
-    return 0;
-}

package/dist/cli/commands/sessions/window.d.ts

@@ -1,3 +0,0 @@
-import { type Context } from '../context.js';
-export declare function show(ctx: Context): Promise<number>;
-export declare function hide(ctx: Context): Promise<number>;

package/dist/cli/commands/sessions/window.js

@@ -1,18 +0,0 @@
-import { requireOnPc, requireRunning } from '../context.js';
-import { SandboxService } from '../../services/index.js';
-import { useSharedSandbox } from '../shared-use.js';
-export async function show(ctx) {
-    requireOnPc('show');
-    requireRunning();
-    await useSharedSandbox(ctx, { kind: 'owner-only', what: 'show the window', window: true });
-    new SandboxService(ctx).showWindow();
-    return 0;
-}
-export async function hide(ctx) {
-    requireOnPc('hide');
-    requireRunning();
-    await useSharedSandbox(ctx, { kind: 'owner-only', what: 'hide the window', window: true });
-    await new SandboxService(ctx).hideWindow();
-    console.log('Sandbox window hidden. Bring it back with: sbx-show');
-    return 0;
-}

package/dist/cli/menu/settings/path-kind.js

@@ -1,44 +0,0 @@
-/** Top-level settings whose list entries are folders or files, and the single settings that are one. */
-const KINDS = {
-    'storage.root': 'dir',
-    'projects.roots': 'dir',
-    'projects.exclude': 'dir',
-    'projects.declinedRoots': 'dir',
-    'claudeProfile.hostDir': 'dir',
-    'claudeProfile.globalStateFile': 'file',
-    scripts: 'file',
-};
-/** The kind of path a setting holds (its key without list positions), or undefined when it is not a path. */
-export function pathKindOf(key) {
-    const id = key.join('.');
-    const last = key[key.length - 1] ?? '';
-    if (KINDS[id])
-        return KINDS[id];
-    if (key[0] === 'mappings' && last === 'host')
-        return 'dir';
-    if (last === 'hostDir')
-        return 'dir';
-    if (/(Dir|Folder)$/.test(last))
-        return 'dir';
-    if (/File$/.test(last))
-        return 'file';
-    return undefined;
-}
-/** Words that are fine instead of a path ("auto"), read from the setting's description. */
-export function pathLiterals(node) {
-    return /"auto"/.test(node.description ?? '') ? ['auto'] : [];
-}
-/** Picks a folder or file in the path picker; typing a path (or an allowed word) still works. */
-export function askPath(app, o) {
-    return app.pickPath({
-        path: o.path,
-        title: o.title,
-        about: o.about,
-        initial: o.initial,
-        files: o.kind === 'file',
-        use: o.kind === 'file' ? 'use this file' : 'use this folder',
-        literals: o.literals,
-        relative: true,
-        validate: o.validate,
-    });
-}