bx-mac 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dirk Holtwick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# bx
+
+Launch VSCode, a terminal, Claude Code, or any command in a macOS sandbox. Your tools can only see the project you're working on — not your private files, SSH keys, or other repositories.
+
+## Why?
+
+AI-powered coding tools like Claude Code, Copilot, or Cline run with broad file system access. A misguided tool call or hallucinated path could accidentally read your SSH keys, credentials, tax documents, or private photos.
+
+**bx** wraps any application in a macOS sandbox (`sandbox-exec`) that blocks access to everything except the project directory you explicitly specify. No containers, no VMs, no setup — just one command.
+
+## What it does
+
+- Blocks access to `~/Documents`, `~/Desktop`, `~/Downloads`, and all other personal folders
+- Blocks access to sibling projects — only the directory you specify is accessible
+- Protects sensitive dotdirs like `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.cargo` by default
+- Keeps VSCode, extensions, shell, Node.js, and other tooling fully functional
+- Generates sandbox rules dynamically based on your actual `$HOME` contents
+- Supports `.bxignore` to hide secrets like `.env` files within a project
+- Supports `~/.bxallow` to grant access to shared utility directories
+
+## What it doesn't do
+
+- **No network restrictions** — API calls, git push/pull, npm install all work normally
+- **No process isolation** — this is file-level sandboxing, not a container
+- **No protection against root/sudo** — the sandbox applies to the user-level process
+- **macOS only** — relies on `sandbox-exec` which is an Apple-specific technology
+- **Not a security guarantee** — `sandbox-exec` is undocumented and may have limitations; treat this as a safety net, not a vault
+
+## Requirements
+
+- macOS (tested on Sequoia / macOS 15)
+- Node.js >= 22
+- Visual Studio Code installed in `/Applications` (for `code` mode)
+
+## Install
+
+```bash
+# Homebrew
+brew install holtwick/tap/bx
+
+# npm
+npm install -g bx-mac
+
+# From source
+git clone https://github.com/holtwick/bx-mac.git
+cd bx-mac
+pnpm install && pnpm build
+pnpm link -g
+```
+
+## Quick start
+
+```bash
+# Launch VSCode with sandbox protection
+bx ~/work/my-project
+```
+
+That's it. VSCode opens with full access to `~/work/my-project` and nothing else.
+
+## Modes
+
+```bash
+bx [workdir]                            # VSCode (default)
+bx code [workdir]                       # VSCode (explicit)
+bx term [workdir]                       # sandboxed login shell ($SHELL -l)
+bx claude [workdir]                     # Claude Code CLI
+bx exec [workdir] -- command [args...]  # arbitrary command
+```
+
+If no directory is given, the current directory is used.
+
+### Examples
+
+```bash
+# Work on a project in a sandboxed terminal
+bx term ~/work/my-project
+
+# Let Claude Code work on a project without access to anything else
+bx claude ~/work/my-project
+
+# Run a script in a sandbox
+bx exec ~/work/my-project -- python train.py
+
+# VSCode with verbose output
+bx --verbose ~/work/my-project
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--verbose` | Print the generated sandbox profile to stderr |
+| `--profile-sandbox` | Use an isolated VSCode profile (separate extensions and settings, `code` mode only) |
+
+## Configuration
+
+bx uses three optional config files, all with the same format: one entry per line, `#` for comments.
+
+### `~/.bxallow`
+
+Allow extra directories beyond the working directory. Paths are relative to `$HOME`.
+
+```gitignore
+# Shared shell scripts and utilities
+work/bin
+# Shared libraries used across projects
+shared/libs
+```
+
+### `~/.bxignore`
+
+Block additional dotdirs or files in your home. Paths are relative to `$HOME`.
+
+```gitignore
+# Cloud provider credentials
+.aws
+.azure
+.kube
+.config/gcloud
+```
+
+These are blocked **in addition** to the built-in protected list:
+
+> `.Trash` `.ssh` `.gnupg` `.docker` `.zsh_sessions` `.cargo` `.gradle` `.gem`
+
+### `<project>/.bxignore`
+
+Block paths within the working directory itself. Supports glob patterns.
+
+```gitignore
+# Environment files with secrets
+.env
+.env.*
+
+# Credentials and keys
+secrets/
+**/*.pem
+**/*.key
+```
+
+## How it works
+
+bx generates a macOS sandbox profile at launch time:
+
+1. **Scan** `$HOME` for non-hidden directories
+2. **Block** each one individually with a `(deny file* (subpath ...))` rule
+3. **Skip** the working directory, `~/Library`, dotfiles, and any paths from `~/.bxallow`
+4. **Descend** into parent directories of allowed paths to block only siblings (because SBPL deny rules always override allow rules — you can't deny a parent and allow a child)
+5. **Append** deny rules for protected dotdirs and `.bxignore` entries
+6. **Write** the profile to `/tmp`, launch VSCode via `sandbox-exec`, clean up on exit
+
+### Why not a simple deny-all + allow?
+
+Apple's Sandbox Profile Language (SBPL) has a critical quirk: **`deny` always wins over `allow`**, regardless of rule order. This means:
+
+```scheme
+;; Does NOT work — the deny still blocks myproject
+(deny file* (subpath "/Users/me/work"))
+(allow file* (subpath "/Users/me/work/myproject"))
+```
+
+Additionally, a broad `(deny file* (subpath HOME))` breaks `kqueue`/FSEvents file watchers and SQLite `fcntl` locks, causing VSCode errors even for paths that should be allowed.
+
+bx avoids both issues by **never denying a parent of an allowed path**. Instead, it walks the directory tree and denies only the specific siblings that should be blocked.
+
+## Tips
+
+**See what's happening:** Use `--verbose` to inspect the generated profile before trusting it with sensitive work.
+
+**Test the sandbox:** Try reading a blocked file from VSCode's terminal:
+
+```bash
+cat ~/Documents/something.txt   # Should fail with "Operation not permitted"
+cat ~/Desktop/file.txt           # Should fail
+ls ~/work/other-project/         # Should fail
+```
+
+## Safety checks
+
+bx detects and prevents problematic scenarios:
+
+- **Sandbox nesting:** If `CODEBOX_SANDBOX=1` is set (automatically passed to child processes), bx refuses to start — nested `sandbox-exec` causes silent failures.
+- **Unknown sandbox:** On startup, bx probes `~/Documents`, `~/Desktop`, and `~/Downloads`. If any return `EPERM`, another sandbox is already active — bx aborts.
+- **VSCode terminal:** If `VSCODE_PID` is set, bx warns that it will launch a *new* instance, not sandbox the current one.
+
+## Known limitations
+
+- **File watcher warnings:** VSCode may log `EPERM` errors for `fs.watch()` on some paths. These are cosmetic and don't affect functionality.
+- **SQLite warnings:** `state.vscdb` errors may appear in logs when VSCode's state database paths are affected. Extensions still work correctly.
+- **`sandbox-exec` is undocumented:** Apple provides no official documentation for SBPL. The tool works in practice but could change with OS updates.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/bx.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { accessSync, constants, cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region src/index.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+if (process.env.CODEBOX_SANDBOX === "1") {
+	console.error("sandbox: ERROR — already running inside a bx sandbox.");
+	console.error("sandbox: Nesting sandbox-exec causes silent failures. Aborting.");
+	process.exit(1);
+}
+if (process.env.VSCODE_PID) {
+	console.error("sandbox: WARNING — running from inside a VSCode terminal.");
+	console.error("sandbox: This will launch a *new* instance in a sandbox.");
+	console.error("sandbox: The current VSCode instance will NOT be sandboxed.");
+}
+function isAlreadySandboxed() {
+	for (const dir of [
+		"Documents",
+		"Desktop",
+		"Downloads"
+	]) {
+		const target = join(process.env.HOME, dir);
+		try {
+			accessSync(target, constants.R_OK);
+		} catch (e) {
+			if (e.code === "EPERM") return true;
+		}
+	}
+	return false;
+}
+if (isAlreadySandboxed()) {
+	console.error("sandbox: ERROR — already running inside a sandbox!");
+	console.error("sandbox: Nesting sandbox-exec may cause silent failures. Aborting.");
+	process.exit(1);
+}
+const MODES = [
+	"code",
+	"term",
+	"claude",
+	"exec"
+];
+const rawArgs = process.argv.slice(2);
+const verbose = rawArgs.includes("--verbose");
+const profileSandbox = rawArgs.includes("--profile-sandbox");
+const positional = rawArgs.filter((a) => !a.startsWith("--"));
+const doubleDashIdx = rawArgs.indexOf("--");
+const execCmd = doubleDashIdx >= 0 ? rawArgs.slice(doubleDashIdx + 1) : [];
+const beforeDash = doubleDashIdx >= 0 ? rawArgs.slice(0, doubleDashIdx).filter((a) => !a.startsWith("--")) : positional;
+let mode = "code";
+let workArg = ".";
+if (beforeDash.length > 0 && MODES.includes(beforeDash[0])) {
+	mode = beforeDash[0];
+	workArg = beforeDash[1] ?? ".";
+} else if (beforeDash.length > 0) workArg = beforeDash[0];
+if (mode === "exec" && execCmd.length === 0) {
+	console.error("sandbox: exec mode requires a command after \"--\"");
+	console.error("usage: bx exec [workdir] -- command [args...]");
+	process.exit(1);
+}
+const HOME = process.env.HOME;
+const SCRIPT_DIR = __dirname;
+const WORK_DIR = resolve(workArg);
+const allowedDirs = new Set([WORK_DIR]);
+const sandboxAllowPath = join(HOME, ".bxallow");
+if (existsSync(sandboxAllowPath)) for (const raw of readFileSync(sandboxAllowPath, "utf-8").split("\n")) {
+	const line = raw.trim();
+	if (!line || line.startsWith("#")) continue;
+	const absolute = resolve(HOME, line);
+	if (existsSync(absolute) && statSync(absolute).isDirectory()) allowedDirs.add(absolute);
+}
+const VSCODE_APP = "/Applications/Visual Studio Code.app/Contents/MacOS/Electron";
+const VSCODE_DATA = join(HOME, ".vscode-sandbox");
+const VSCODE_EXTENSIONS_GLOBAL = join(HOME, ".vscode", "extensions");
+const VSCODE_EXTENSIONS_LOCAL = join(VSCODE_DATA, "extensions");
+if (mode === "code" && profileSandbox) {
+	mkdirSync(VSCODE_DATA, { recursive: true });
+	if (!existsSync(VSCODE_EXTENSIONS_LOCAL) && existsSync(VSCODE_EXTENSIONS_GLOBAL)) {
+		console.error("sandbox: copying extensions from global install...");
+		cpSync(VSCODE_EXTENSIONS_GLOBAL, VSCODE_EXTENSIONS_LOCAL, { recursive: true });
+	}
+}
+function collectBlockedDirs(parentDir) {
+	const blocked = [];
+	for (const name of readdirSync(parentDir)) {
+		if (name.startsWith(".")) continue;
+		const fullPath = join(parentDir, name);
+		if (!statSync(fullPath).isDirectory()) continue;
+		if (parentDir === HOME && name === "Library") continue;
+		if (SCRIPT_DIR.startsWith(fullPath + "/") || SCRIPT_DIR === fullPath) continue;
+		if (allowedDirs.has(fullPath)) continue;
+		if ([...allowedDirs].some((d) => d.startsWith(fullPath + "/"))) {
+			blocked.push(...collectBlockedDirs(fullPath));
+			continue;
+		}
+		blocked.push(fullPath);
+	}
+	return blocked;
+}
+const blockedDirs = collectBlockedDirs(HOME);
+const PROTECTED_DOTDIRS = [
+	".Trash",
+	".ssh",
+	".gnupg",
+	".docker",
+	".zsh_sessions",
+	".cargo",
+	".gradle",
+	".gem"
+];
+const ignoredPaths = PROTECTED_DOTDIRS.map((d) => join(HOME, d));
+function parseSandboxIgnore(filePath, baseDir) {
+	if (!existsSync(filePath)) return;
+	for (const raw of readFileSync(filePath, "utf-8").split("\n")) {
+		const line = raw.trim();
+		if (!line || line.startsWith("#")) continue;
+		const matches = globSync(line, { cwd: baseDir });
+		for (const match of matches) ignoredPaths.push(resolve(baseDir, match));
+	}
+}
+parseSandboxIgnore(join(HOME, ".bxignore"), HOME);
+parseSandboxIgnore(join(WORK_DIR, ".bxignore"), WORK_DIR);
+const extraIgnored = ignoredPaths.length - PROTECTED_DOTDIRS.length;
+if (extraIgnored > 0) console.error(`sandbox: .bxignore hides ${extraIgnored} extra path(s)`);
+const profile = `; Auto-generated sandbox profile
+; Working directory: ${WORK_DIR}
+
+(version 1)
+(allow default)
+
+; Blocked directories (auto-generated from $HOME contents)
+(deny file*
+${blockedDirs.map((dir) => `  (subpath "${dir}")`).join("\n")}
+)
+
+${ignoredPaths.length > 0 ? `
+; Hidden paths from .bxignore
+(deny file*
+${ignoredPaths.map((p) => {
+	return existsSync(p) && statSync(p).isDirectory() ? `  (subpath "${p}")` : `  (literal "${p}")`;
+}).join("\n")}
+)
+` : ""}
+`;
+const profilePath = join("/tmp", `bx-${process.pid}.sb`);
+writeFileSync(profilePath, profile);
+console.error(`sandbox: ${mode} mode, working directory: ${WORK_DIR}`);
+if (verbose) {
+	console.error("\n--- Generated sandbox profile ---");
+	console.error(profile);
+	console.error("--- End of profile ---\n");
+}
+function buildCommand() {
+	switch (mode) {
+		case "code": {
+			const args = ["--no-sandbox"];
+			if (profileSandbox) {
+				args.push("--user-data-dir", join(VSCODE_DATA, "data"));
+				args.push("--extensions-dir", VSCODE_EXTENSIONS_LOCAL);
+			}
+			args.push(WORK_DIR);
+			return {
+				bin: VSCODE_APP,
+				args
+			};
+		}
+		case "term": return {
+			bin: process.env.SHELL ?? "/bin/zsh",
+			args: ["-l"]
+		};
+		case "claude": return {
+			bin: "claude",
+			args: [WORK_DIR]
+		};
+		case "exec": return {
+			bin: execCmd[0],
+			args: execCmd.slice(1)
+		};
+	}
+}
+const cmd = buildCommand();
+spawn("sandbox-exec", [
+	"-f",
+	profilePath,
+	"-D",
+	`HOME=${HOME}`,
+	"-D",
+	`WORK=${WORK_DIR}`,
+	cmd.bin,
+	...cmd.args
+], {
+	cwd: WORK_DIR,
+	stdio: "inherit",
+	env: {
+		...process.env,
+		CODEBOX_SANDBOX: "1"
+	}
+}).on("close", (code) => {
+	rmSync(profilePath, { force: true });
+	process.exit(code ?? 0);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "bx-mac",
+  "version": "0.1.5",
+  "description": "Launch apps in a macOS sandbox — only the project directory is accessible",
+  "type": "module",
+  "bin": {
+    "bx": "dist/bx.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rolldown -c",
+    "release": "./scripts/release.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sandbox",
+    "macos",
+    "security",
+    "vscode",
+    "claude"
+  ],
+  "author": "Dirk Holtwick",
+  "license": "MIT",
+  "devDependencies": {
+    "rolldown": "^1.0.0-rc.12"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.33.0"
+}