windows-development-sandbox 1.1.0 → 1.4.1

package/schemas/config.schema.json

@@ -32,6 +32,62 @@
       "type": "boolean",
       "description": "Map the workspace read-only."
     },
+    "workspaceFilter": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "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": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 500
+          },
+          "description": "Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/."
+        },
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 500
+          },
+          "description": "Let these in although .gitignore lists them, e.g. .env.example, data/fixtures/."
+        }
+      },
+      "additionalProperties": false
+    },
+    "audit": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "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": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "description": "Days the audit log is kept."
+        },
+        "maxMb": {
+          "type": "integer",
+          "minimum": 5,
+          "maximum": 5000,
+          "description": "Most space the audit log may take, in MB (older days go first). Days before today are compressed."
+        },
+        "processes": {
+          "type": "boolean",
+          "description": "Record every program started in the sandbox with its command line (Windows process auditing; repeated runs are counted, not listed)."
+        },
+        "files": {
+          "type": "boolean",
+          "description": "Record the files changed in the project while the sandbox runs."
+        }
+      },
+      "additionalProperties": false
+    },
     "mappings": {
       "type": "array",
       "items": {
@@ -43,8 +99,10 @@
             "description": "Folder on this PC (relative paths are relative to the config file)."
           },
           "guest": {
+            "description": "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 (shown as F: at boot). Leave it out to use the same path as on this PC (a folder inside the project stays where it is in the project). A path the sandbox cannot use (C:\\Windows\\..., C:\\Users\\..., one already in use) goes to C:\\Mapped\\<drive>\\<path> instead, and the launch says so.",
             "type": "string",
-            "description": "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."
+            "minLength": 1,
+            "maxLength": 1024
           },
           "readOnly": {
             "type": "boolean",
@@ -102,6 +160,12 @@
           ],
           "description": "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": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 262144,
+          "description": "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": {
           "type": "integer",
           "minimum": 0,
@@ -139,6 +203,10 @@
         "headless": {
           "type": "boolean",
           "description": "Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends."
+        },
+        "keepAwake": {
+          "type": "boolean",
+          "description": "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)."
         }
       },
       "additionalProperties": false
@@ -159,6 +227,15 @@
           "type": "string",
           "pattern": "^[A-Za-z0-9_-]+$",
           "description": "Name of the persistent data set (C:\\AgentData) shared by all workspaces."
+        },
+        "markSandboxFiles": {
+          "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."
+        },
+        "warnDataGb": {
+          "type": "number",
+          "minimum": 0,
+          "description": "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."
         }
       },
       "additionalProperties": false
@@ -169,6 +246,59 @@
         "blockPrivateRanges": {
           "type": "boolean",
           "description": "Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox."
+        },
+        "allowOnly": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 253,
+            "pattern": "^(@developer|(\\*\\.)?([a-zA-Z0-9-]+\\.)*[a-zA-Z0-9-]+)$"
+          },
+          "description": "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": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 253,
+            "pattern": "^([a-zA-Z0-9-]+\\.)*[a-zA-Z0-9-]+$"
+          },
+          "description": "Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox's hosts file sends them nowhere)."
+        },
+        "forwardPorts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "pc": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535,
+                "description": "The port on this PC (localhost only)."
+              },
+              "sandbox": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535,
+                "description": "The port inside the sandbox (a server there may listen on localhost only)."
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": "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": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\d{1,3}(\\.\\d{1,3}){3}$"
+          },
+          "description": "DNS servers for the sandbox instead of your network's, e.g. 1.1.1.1 and 9.9.9.9."
+        },
+        "proxy": {
+          "type": "string",
+          "pattern": "^(https?:\\/\\/[^\\s]+)?$",
+          "description": "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."
         }
       },
       "additionalProperties": false
@@ -216,6 +346,16 @@
             }
           },
           "additionalProperties": false
+        },
+        "conpty": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "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."
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -725,6 +865,22 @@
             "enabled": {
               "type": "boolean",
               "description": "Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist."
+            },
+            "setup": {
+              "type": "boolean",
+              "description": "Point VS Code at the sandbox's own tools (JDK, Python, Go, compilers, .NET, Git, PowerShell 7 and Git Bash terminals) and install the language extensions for the toolchains in use."
+            },
+            "recommended": {
+              "type": "boolean",
+              "description": "Also install the extensions a project recommends in its .vscode/extensions.json."
+            },
+            "extensions": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[\\w-]+\\.[\\w-]+$"
+              },
+              "description": "More extensions to install in every sandbox, e.g. eamodio.gitlens, ms-azuretools.vscode-docker."
             }
           },
           "additionalProperties": false
@@ -999,6 +1155,141 @@
       },
       "additionalProperties": false
     },
+    "apps": {
+      "type": "object",
+      "properties": {
+        "install": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "notepadpp",
+              "sublime",
+              "neovim",
+              "dbeaver",
+              "pgadmin",
+              "heidisql",
+              "sqlitebrowser",
+              "compass",
+              "redisinsight",
+              "dbgate",
+              "beekeeper",
+              "dynamodb-admin",
+              "bruno",
+              "insomnia",
+              "sourcegit",
+              "githubdesktop",
+              "lazygit",
+              "7zip",
+              "winmerge",
+              "everything",
+              "sysinternals",
+              "imhex",
+              "chrome",
+              "firefox",
+              "godot",
+              "blender",
+              "love",
+              "defold",
+              "pixelorama",
+              "tiled",
+              "kubectl",
+              "helm",
+              "k9s",
+              "terraform",
+              "azure-cli",
+              "gcloud",
+              "aws-cli",
+              "drawio",
+              "pandoc",
+              "mitmproxy",
+              "xh",
+              "grpcurl",
+              "k6",
+              "jq",
+              "yq",
+              "ripgrep",
+              "fd",
+              "bat",
+              "fzf",
+              "delta",
+              "just",
+              "hyperfine",
+              "watchexec",
+              "protoc",
+              "ninja",
+              "ffmpeg",
+              "sqlite",
+              "shellcheck",
+              "gitleaks"
+            ]
+          },
+          "description": "Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept."
+        },
+        "custom": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]{0,40}$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80,
+                "description": "The name on the desktop shortcut, e.g. \"My Tool\"."
+              },
+              "github": {
+                "description": "GitHub repository (owner/repo): the file comes from its latest release.",
+                "type": "string",
+                "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+              },
+              "asset": {
+                "description": "With github: a pattern (regular expression) matching the release file, e.g. windows.*x64\\.zip$",
+                "type": "string",
+                "maxLength": 200
+              },
+              "url": {
+                "description": "Or a direct https:// download link (zip, 7z, exe or msi).",
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^https:\\/\\/.*"
+              },
+              "sha256": {
+                "description": "SHA-256 of the download (GitHub releases usually publish one; then this is not needed).",
+                "type": "string",
+                "pattern": "^[0-9a-fA-F]{64}$"
+              },
+              "unpack": {
+                "description": "archive (zip, 7z, tar: the default), file (a single .exe), nsis (an installer 7-Zip can open) or msi.",
+                "type": "string",
+                "enum": [
+                  "archive",
+                  "file",
+                  "nsis",
+                  "msi"
+                ]
+              },
+              "exe": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200,
+                "description": "The program to start (found anywhere in the download), e.g. mytool.exe."
+              },
+              "cli": {
+                "description": "A command-line tool: its folder goes on PATH instead of getting a desktop shortcut.",
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": "Programs of your own: a GitHub release or a download link, and the program to start. Installed like the catalogue apps."
+        }
+      },
+      "additionalProperties": false
+    },
     "claudeProfile": {
       "type": "object",
       "properties": {
@@ -1032,11 +1323,23 @@
         },
         "syncHistory": {
           "type": "boolean",
-          "description": "Bring all conversation history in, and sync new history back (path-translated)."
+          "description": "Bring conversation history in, and sync new history back (path-translated)."
+        },
+        "historyScope": {
+          "type": "string",
+          "enum": [
+            "project",
+            "all"
+          ],
+          "description": "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": {
           "type": "boolean",
-          "description": "Bring claude-mem data in, and its database back when the sandbox closes."
+          "description": "Bring claude-mem data into the sandbox (its settings and backups stay on this PC)."
+        },
+        "syncClaudeMemBack": {
+          "type": "boolean",
+          "description": "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."
         }
       },
       "additionalProperties": false
@@ -1148,6 +1451,18 @@
           },
           "description": "Parent folders you said no to (not asked again)."
         },
+        "allowOutsideMappings": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "ask"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "A project's .sandbox-config.json may map folders from outside the project (e.g. a game folder on another drive). \"ask\" = an interactive launch asks once per project and set of folders, and remembers your answer; true = always allowed (still listed when you approve the file); false = never (the launch stops and says which folders). Only your own settings decide this, never a project file."
+        },
         "wsbShare": {
           "type": "boolean",
           "description": "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/schemas/sandbox-config.schema.json

@@ -32,6 +32,24 @@
       "type": "boolean",
       "description": "Map this project read-only."
     },
+    "workspaceFilter": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "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": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 500
+          },
+          "description": "Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/."
+        }
+      },
+      "additionalProperties": false
+    },
     "mappings": {
       "type": "array",
       "items": {
@@ -43,8 +61,10 @@
             "description": "Folder on this PC (relative paths are relative to the config file)."
           },
           "guest": {
+            "description": "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 (shown as F: at boot). Leave it out to use the same path as on this PC (a folder inside the project stays where it is in the project). A path the sandbox cannot use (C:\\Windows\\..., C:\\Users\\..., one already in use) goes to C:\\Mapped\\<drive>\\<path> instead, and the launch says so.",
             "type": "string",
-            "description": "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."
+            "minLength": 1,
+            "maxLength": 1024
           },
           "readOnly": {
             "type": "boolean",
@@ -57,12 +77,11 @@
         },
         "required": [
           "host",
-          "guest",
           "readOnly"
         ],
         "additionalProperties": false
       },
-      "description": "Extra folders (relative to this file)."
+      "description": "Extra folders (relative paths are relative to this file), e.g. a read-only data folder at another place in the sandbox. Folders outside the project are used only as your projects.allowOutsideMappings setting allows (by default you are asked once)."
     },
     "scripts": {
       "type": "array",
@@ -137,6 +156,10 @@
         "headless": {
           "type": "boolean",
           "description": "Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends."
+        },
+        "keepAwake": {
+          "type": "boolean",
+          "description": "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)."
         }
       },
       "additionalProperties": false
@@ -145,7 +168,17 @@
       "type": "object",
       "properties": {
         "blockPrivateRanges": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox."
+        },
+        "blockHosts": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 253,
+            "pattern": "^([a-zA-Z0-9-]+\\.)*[a-zA-Z0-9-]+$"
+          },
+          "description": "Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox's hosts file sends them nowhere)."
         }
       },
       "additionalProperties": false
@@ -701,6 +734,22 @@
             "enabled": {
               "type": "boolean",
               "description": "Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist."
+            },
+            "setup": {
+              "type": "boolean",
+              "description": "Point VS Code at the sandbox's own tools (JDK, Python, Go, compilers, .NET, Git, PowerShell 7 and Git Bash terminals) and install the language extensions for the toolchains in use."
+            },
+            "recommended": {
+              "type": "boolean",
+              "description": "Also install the extensions a project recommends in its .vscode/extensions.json."
+            },
+            "extensions": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[\\w-]+\\.[\\w-]+$"
+              },
+              "description": "More extensions to install in every sandbox, e.g. eamodio.gitlens, ms-azuretools.vscode-docker."
             }
           },
           "additionalProperties": false
@@ -920,20 +969,86 @@
       },
       "additionalProperties": false
     },
-    "claudeProfile": {
+    "apps": {
       "type": "object",
       "properties": {
-        "enabled": {
-          "type": "boolean",
-          "description": "Copy selected Claude settings from this PC into the sandbox."
-        },
-        "include": {
+        "install": {
           "type": "array",
           "items": {
             "type": "string",
-            "pattern": "^[A-Za-z0-9._-]+$"
+            "enum": [
+              "notepadpp",
+              "sublime",
+              "neovim",
+              "dbeaver",
+              "pgadmin",
+              "heidisql",
+              "sqlitebrowser",
+              "compass",
+              "redisinsight",
+              "dbgate",
+              "beekeeper",
+              "dynamodb-admin",
+              "bruno",
+              "insomnia",
+              "sourcegit",
+              "githubdesktop",
+              "lazygit",
+              "7zip",
+              "winmerge",
+              "everything",
+              "sysinternals",
+              "imhex",
+              "chrome",
+              "firefox",
+              "godot",
+              "blender",
+              "love",
+              "defold",
+              "pixelorama",
+              "tiled",
+              "kubectl",
+              "helm",
+              "k9s",
+              "terraform",
+              "azure-cli",
+              "gcloud",
+              "aws-cli",
+              "drawio",
+              "pandoc",
+              "mitmproxy",
+              "xh",
+              "grpcurl",
+              "k6",
+              "jq",
+              "yq",
+              "ripgrep",
+              "fd",
+              "bat",
+              "fzf",
+              "delta",
+              "just",
+              "hyperfine",
+              "watchexec",
+              "protoc",
+              "ninja",
+              "ffmpeg",
+              "sqlite",
+              "shellcheck",
+              "gitleaks"
+            ]
           },
-          "description": "Files and folders copied from it."
+          "description": "Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept."
+        }
+      },
+      "additionalProperties": false
+    },
+    "claudeProfile": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Copy selected Claude settings from this PC into the sandbox."
         },
         "overwrite": {
           "type": "boolean",
@@ -945,11 +1060,11 @@
         },
         "syncHistory": {
           "type": "boolean",
-          "description": "Bring all conversation history in, and sync new history back (path-translated)."
+          "description": "Bring conversation history in, and sync new history back (path-translated)."
         },
         "syncClaudeMem": {
           "type": "boolean",
-          "description": "Bring claude-mem data in, and its database back when the sandbox closes."
+          "description": "Bring claude-mem data into the sandbox (its settings and backups stay on this PC)."
         }
       },
       "additionalProperties": false