bx-mac 0.11.0 → 1.0.0

package/README.md

@@ -17,7 +17,7 @@ AI-powered coding tools like Claude Code, Copilot, or Cline run with **broad fil
 bx ~/work/my-project
 ```
 
-That's it. 🎉 VSCode opens with full access to `~/work/my-project` and nothing else.
+That's it. 🎉 VSCode opens with full access to `~/work/my-project` and nothing else. Read [the blog post](https://holtwick.de/blog/bx-sandbox) for more background on the motivation behind bx.
 
 Need multiple directories? No problem:
 
@@ -30,6 +30,7 @@ bx ~/work/my-project ~/work/shared-lib
 - 🔒 Blocks `~/Documents`, `~/Desktop`, `~/Downloads`, and all other personal folders
 - 🚧 Blocks sibling projects — only the directory you specify is accessible
 - 🛡️ Protects sensitive dotdirs like `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.cargo`
+- 🏛️ Opinionated protection for `~/Library` — blocks privacy-sensitive subdirectories (Mail, Messages, Photos, Safari, Contacts, …) and containers of password managers/finance apps, while keeping tooling-relevant paths accessible
 - ⚙️ Keeps VSCode, extensions, shell, Node.js, and other tooling fully functional
 - 🔍 Generates sandbox rules dynamically based on your actual `$HOME` contents
 - 📝 Supports `.bxignore` files (searched recursively) to hide secrets like `.env` files within a project
@@ -81,7 +82,7 @@ For app modes, values before `--` define the sandbox scope (`workdir...`). Value
 
 For `xcode`, this distinction is important: the sandbox workdir is **not** passed as an Xcode open argument. Use `--` if you want to open a specific `.xcworkspace` or `.xcodeproj`.
 
-This behavior is configurable per app via `passWorkdirs` in `~/.bxconfig.toml` (default: `true`, built-in `xcode` default: `false`).
+This behavior is configurable per app via `passPaths` in `~/.bxconfig.toml` (default: `true`, built-in `xcode` default: `false`).
 
 GUI app modes are activated in the foreground on launch (best effort), so the opened app should become the frontmost app.
 
@@ -113,6 +114,9 @@ bx zed ~/work/my-project
 # ⚡ Run a script in a sandbox
 bx exec ~/work/my-project -- python train.py
 
+# 🔀 Run in the background (terminal stays free)
+bx --background code ~/work/my-project
+
 # 🔍 Preview what will be protected (no launch)
 bx --dry ~/work/my-project
 
@@ -126,6 +130,7 @@ bx --verbose ~/work/my-project
 | --- | --- |
 | `--dry` | Show a tree of all protected, read-only, and accessible paths — don't launch anything |
 | `--verbose` | Print the generated sandbox profile plus launch details (binary, arguments, cwd, focus command) |
+| `--background` | Run the app detached in the background (like `nohup &`), output goes to `/tmp/bx-<pid>.log` |
 | `--profile-sandbox` | Use an isolated VSCode profile (separate extensions/settings, `code` mode only) |
 
 On normal runs, bx also prints a short policy summary (number of workdirs, blocked directories, hidden paths, and read-only directories).
@@ -154,43 +159,44 @@ path = "/usr/local/bin/code"
 
 | Field | Description |
 | --- | --- |
-| `mode` | Inherit from another app (e.g. `"code"`, `"cursor"`) — only `workdirs` / overrides needed |
+| `mode` | Inherit from another app (e.g. `"code"`, `"cursor"`) — only `paths` / overrides needed |
 | `bundle` | macOS bundle identifier — used with `mdfind` to find the app automatically |
 | `binary` | Relative path to the executable inside the `.app` bundle |
 | `path` | Absolute path to the executable **or** `.app` bundle (highest priority, skips discovery) |
 | `fallback` | Absolute fallback path if `mdfind` discovery fails |
 | `args` | Extra arguments always passed to the app |
-| `passWorkdirs` | Whether `workdir...` is forwarded as app launch args (`true`/`false`) |
-| `workdirs` | Default working directories when none are given on the CLI (supports `~/` paths) |
+| `passPaths` | Paths passed as app launch args (`true`/`false`/`N`/`["~/p1", "~/p2"]`) |
+| `paths` | Default working directories when none are given on the CLI (supports `~/` paths) |
+| `background` | Run the app detached in the background by default (`true`/`false`) |
 
 **Resolution order:** `path` → `mdfind` by `bundle` + `binary` → `fallback`
 
-`passWorkdirs` controls launch argument behavior and is independent of sandbox scope. Even with `passWorkdirs = false`, the provided `workdir...` still defines what the sandbox can access.
+`passPaths` controls launch argument behavior and is independent of sandbox scope. Even with `passPaths = false`, the provided `workdir...` still defines what the sandbox can access. Use `passPaths = 1` to pass only the first path as a launch argument, or `passPaths = ["~/specific/path"]` to pass explicit paths instead of workdirs.
 
-**Workdir shortcuts with `mode`** let you create named entries that inherit everything from an existing app — just set `mode` and `workdirs`:
+**Workdir shortcuts with `mode`** let you create named entries that inherit everything from an existing app — just set `mode` and `paths`:
 
 ```toml
 # "bx myproject" opens VSCode with these directories
 [myproject]
 mode = "code"
-workdirs = ["~/work/my-project", "~/work/shared-lib"]
+paths = ["~/work/my-project", "~/work/shared-lib"]
 
 # "bx ios" opens Xcode with this directory
 [ios]
 mode = "xcode"
-workdirs = ["~/work/my-ios-app"]
+paths = ["~/work/my-ios-app"]
 ```
 
 Running `bx myproject` inherits VSCode's bundle, binary, args, and everything else — no need to repeat the full app configuration. Own fields override inherited ones, so you can still customize specific settings. Chaining is supported (e.g. `myproject` → `cursor` → `code`).
 
-**Preconfigured workdirs** also work directly on app definitions:
+**Preconfigured paths** also work directly on app definitions:
 
 ```toml
 [code]
-workdirs = ["~/work/my-project", "~/work/shared-lib"]
+paths = ["~/work/my-project", "~/work/shared-lib"]
 ```
 
-Running `bx code` (without arguments) will then open VSCode with both directories sandboxed. CLI arguments always override configured workdirs.
+Running `bx code` (without arguments) will then open VSCode with both directories sandboxed. CLI arguments always override configured paths.
 
 When overriding a built-in app, only the specified fields are replaced — unset fields keep their defaults. See [`bxconfig.example.toml`](bxconfig.example.toml) for a complete reference.
 
@@ -216,9 +222,11 @@ ro:reference/docs
 ro:shared/toolchain
 ```
 
-Deny rules are applied **in addition** to the built-in protected list:
+Deny rules are applied **in addition** to the built-in protected lists:
 
-> 🔒 `.ssh` `.gnupg` `.docker` `.zsh_sessions` `.cargo` `.gradle` `.gem`
+> 🔒 **Dotdirs:** `.ssh` `.gnupg` `.docker` `.zsh_sessions` `.cargo` `.gradle` `.gem`
+>
+> 🏛️ **Library (opinionated):** `Accounts` `Calendars` `Contacts` `Cookies` `Finance` `Mail` `Messages` `Mobile Documents` `Photos` `Safari` and [others (see full list)](src/profile.ts) — plus containers of password managers & finance apps
 
 ### `<project>/.bxignore`
 
@@ -288,9 +296,10 @@ bx generates a macOS sandbox profile at launch time:
 2. **Block** each one individually with `(deny file* (subpath ...))`
 3. **Skip** all working directories, `~/Library`, dotfiles, and `rw:`/`ro:` paths from `~/.bxignore`
 4. **Descend** into parent directories of allowed paths to block only siblings (because SBPL deny rules always override allow rules)
-5. **Append** deny rules for protected dotdirs, plain entries in `~/.bxignore`, and `.bxignore` files found recursively in each working directory
-6. **Apply** `(deny file-write*)` rules for `ro:` directories (read allowed, write blocked)
-7. **Write** the profile to `/tmp`, launch the app via `sandbox-exec`, clean up on exit
+5. **Protect** an opinionated set of `~/Library` subdirectories (Mail, Messages, Photos, Safari, Contacts, Calendars, …) and app containers matching known password managers and finance apps (1Password, Bitwarden, MoneyMoney, …)
+6. **Append** deny rules for protected dotdirs, plain entries in `~/.bxignore`, and `.bxignore` files found recursively in each working directory
+7. **Apply** `(deny file-write*)` rules for `ro:` directories (read allowed, write blocked)
+8. **Write** the profile to `/tmp`, launch the app via `sandbox-exec`, clean up on exit
 
 ### Why not a simple deny-all + allow?
 
@@ -330,7 +339,7 @@ Or preconfigure them in `~/.bxconfig.toml`:
 
 ```toml
 [code]
-workdirs = ["~/work/project-a", "~/work/project-b"]
+paths = ["~/work/project-a", "~/work/project-b"]
 ```
 
 For VSCode specifically, `--profile-sandbox` forces a separate Electron process via an isolated `--user-data-dir`, but this means separate extensions and settings.
@@ -363,6 +372,10 @@ Some AI coding tools ship with their own sandboxing. bx complements these by pro
 
 These are great when available, but they only protect within their own tool. bx wraps the entire process — so even if a tool's built-in sandbox is misconfigured, disabled, or absent, your files stay protected.
 
+## 🔗 Alternatives
+
+- [Agent Safehouse](https://agent-safehouse.dev/) — macOS kernel-level sandboxing for LLM coding agents via `sandbox-exec`. Deny-first model that blocks write access outside the project directory.
+
 ## 📄 License
 
 MIT — see [LICENSE](LICENSE).

package/dist/bx.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { accessSync, constants, cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, constants, cpSync, existsSync, globSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { execFileSync, spawn } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -797,7 +797,7 @@ const BUILTIN_APPS = {
 		bundle: "com.apple.dt.Xcode",
 		binary: "Contents/MacOS/Xcode",
 		fallback: "/Applications/Xcode.app/Contents/MacOS/Xcode",
-		passWorkdirs: false
+		passPaths: false
 	}
 };
 /** Shell-only built-in modes that are not app definitions */
@@ -806,6 +806,20 @@ const BUILTIN_MODES = [
 	"claude",
 	"exec"
 ];
+function parsePassPaths(val) {
+	if (typeof val === "boolean") return val;
+	if (typeof val === "number" && Number.isInteger(val) && val > 0) return val;
+	if (Array.isArray(val)) {
+		const paths = val.filter((a) => typeof a === "string");
+		if (paths.length > 0) return paths;
+	}
+}
+function parseStringArray(val) {
+	if (Array.isArray(val)) {
+		const items = val.filter((a) => typeof a === "string");
+		if (items.length > 0) return items;
+	}
+}
 function parseAppDef(def) {
 	return {
 		mode: typeof def.mode === "string" ? def.mode : void 0,
@@ -813,9 +827,10 @@ function parseAppDef(def) {
 		binary: typeof def.binary === "string" ? def.binary : void 0,
 		path: typeof def.path === "string" ? def.path : void 0,
 		fallback: typeof def.fallback === "string" ? def.fallback : void 0,
-		args: Array.isArray(def.args) ? def.args.filter((a) => typeof a === "string") : void 0,
-		passWorkdirs: typeof def.passWorkdirs === "boolean" ? def.passWorkdirs : void 0,
-		workdirs: Array.isArray(def.workdirs) ? def.workdirs.filter((a) => typeof a === "string") : void 0
+		args: parseStringArray(def.args),
+		passPaths: parsePassPaths(def.passPaths ?? def.passWorkPaths ?? def.passWorkdirs),
+		paths: parseStringArray(def.paths ?? def.workdirs),
+		background: typeof def.background === "boolean" ? def.background : void 0
 	};
 }
 /**
@@ -835,8 +850,12 @@ function loadConfig(home) {
 			"path",
 			"fallback",
 			"args",
+			"passPaths",
+			"passWorkPaths",
 			"passWorkdirs",
-			"workdirs"
+			"paths",
+			"workdirs",
+			"background"
 		]);
 		for (const [key, val] of Object.entries(doc)) {
 			if (key === "apps") continue;
@@ -1032,14 +1051,6 @@ const ACCESS_PREFIX_RE = /^(RW|RO):(.+)$/i;
 function parseHomeConfig(home, workDirs) {
 	const allowed = new Set(workDirs);
 	const readOnly = /* @__PURE__ */ new Set();
-	const bxallowPath = join(home, ".bxallow");
-	if (existsSync(bxallowPath)) {
-		console.error("sandbox: WARNING — ~/.bxallow is deprecated. Move entries to ~/.bxignore with RW: prefix.");
-		for (const line of parseLines(bxallowPath)) {
-			const absolute = resolve(home, line);
-			if (existsSync(absolute) && statSync(absolute).isDirectory()) allowed.add(absolute);
-		}
-	}
 	for (const line of parseLines(join(home, ".bxignore"))) {
 		const match = line.match(ACCESS_PREFIX_RE);
 		if (!match) continue;
@@ -1265,6 +1276,7 @@ function parseArgs(validModes) {
 	const verbose = rawArgs.includes("--verbose");
 	const dry = rawArgs.includes("--dry");
 	const profileSandbox = rawArgs.includes("--profile-sandbox");
+	const background = rawArgs.includes("--background");
 	const positional = rawArgs.filter((a) => !a.startsWith("--"));
 	const doubleDashIdx = rawArgs.indexOf("--");
 	const appArgs = doubleDashIdx >= 0 ? rawArgs.slice(doubleDashIdx + 1) : [];
@@ -1291,6 +1303,7 @@ function parseArgs(validModes) {
 		verbose,
 		dry,
 		profileSandbox,
+		background,
 		appArgs,
 		implicit: implicitWorkdirs
 	};
@@ -1300,8 +1313,12 @@ function parseArgs(validModes) {
 function isBuiltinMode(mode) {
 	return BUILTIN_MODES.includes(mode);
 }
-function shouldPassWorkdirs(app) {
-	return app.passWorkdirs !== false;
+function getPassPaths(app, workDirs, home) {
+	const val = app.passPaths;
+	if (val === false) return [];
+	if (typeof val === "number") return workDirs.slice(0, val);
+	if (Array.isArray(val)) return val.map((p) => p.replace(/^~\//, home + "/"));
+	return workDirs;
 }
 function appBundleFromPath(path) {
 	if (path.endsWith(".app")) return path;
@@ -1372,7 +1389,7 @@ function buildAppCommand(mode, workDirs, home, profileSandbox, appArgs, apps) {
 	}
 	if (app.args) args.push(...app.args);
 	if (appArgs.length > 0) args.push(...appArgs);
-	if (shouldPassWorkdirs(app)) args.push(...workDirs);
+	args.push(...getPassPaths(app, workDirs, home));
 	return {
 		bin,
 		args
@@ -1462,6 +1479,7 @@ const OPTIONS_TEXT = `
 Options:
   --dry                show what will be protected, don't launch
   --verbose            print the generated sandbox profile
+  --background         run in background, log output to /tmp/bx-<pid>.log
   --profile-sandbox    use an isolated VSCode profile (code mode only)
   -v, --version        show version
   -h, --help           show this help
@@ -1474,7 +1492,8 @@ Configuration:
                          binary = "..."         relative path in .app bundle
                          path = "..."           explicit executable path
                          args = ["..."]         extra arguments
-                         passWorkdirs = true|false pass workdirs as launch args
+                         passPaths = true|false|N|[...]  paths passed as launch args
+                         background = true      run in background by default
                        built-in apps (code, xcode) can be overridden
   ~/.bxignore          sandbox rules (one per line):
                          path         block access (deny)
@@ -1555,7 +1574,7 @@ function printDryRunTree({ home, blockedDirs, ignoredPaths, readOnlyDirs, workDi
 }
 //#endregion
 //#region package.json
-var version = "0.11.0";
+var version = "1.0.0";
 //#endregion
 //#region src/index.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -1575,16 +1594,16 @@ if (!process$1.env.HOME) {
 const HOME = process$1.env.HOME;
 async function main() {
 	const apps = getAvailableApps(loadConfig(HOME));
-	const { mode, workArgs, verbose, dry, profileSandbox, appArgs, implicit } = parseArgs(getValidModes(apps));
+	const { mode, workArgs, verbose, dry, profileSandbox, background: backgroundFlag, appArgs, implicit } = parseArgs(getValidModes(apps));
 	const app = apps[mode];
-	const workDirs = (implicit && app?.workdirs?.length ? app.workdirs : workArgs).map((a) => resolve(a.replace(/^~\//, HOME + "/")));
-	if (implicit && !app?.workdirs?.length) {
+	const workDirs = (implicit && app?.paths?.length ? app.paths : workArgs).map((a) => realpathSync(resolve(a.replace(/^~\//, HOME + "/"))));
+	if (implicit && !app?.paths?.length) {
 		if (workDirs.some((d) => d === HOME)) {
 			console.error(`\n${fmt.error("no working directory specified and current directory is $HOME")}\n`);
 			console.error(fmt.detail(`Usage:  bx ${mode} <workdir>`));
-			console.error(fmt.detail(`Config: set default workdirs in ~/.bxconfig.toml:\n`));
+			console.error(fmt.detail(`Config: set default paths in ~/.bxconfig.toml:\n`));
 			console.error(fmt.detail(`[${mode}]`));
-			console.error(fmt.detail(`workdirs = ["~/work/my-project"]\n`));
+			console.error(fmt.detail(`paths = ["~/work/my-project"]\n`));
 			process$1.exit(1);
 		}
 		if (!dry) await confirmLaunch(workDirs[0], mode);
@@ -1618,13 +1637,54 @@ async function main() {
 		});
 		process$1.exit(0);
 	}
-	const profilePath = join("/tmp", `bx-${process$1.pid}.sb`);
-	writeFileSync(profilePath, profile);
+	const tmpDir = mkdtempSync(join("/tmp", "bx-"));
+	const profilePath = join(tmpDir, "profile.sb");
+	writeFileSync(profilePath, profile, { mode: 384 });
 	const cmd = buildCommand(mode, workDirs, HOME, profileSandbox, appArgs, apps);
+	const background = backgroundFlag || app?.background === true;
 	const nestedSandboxWarning = getNestedSandboxWarning(mode, apps);
 	if (nestedSandboxWarning) console.error(fmt.detail(nestedSandboxWarning));
-	if (verbose) printLaunchDetails(cmd, workDirs[0], getActivationCommand(mode, apps));
+	printLaunchDetails(cmd, workDirs[0]);
+	if (verbose) {
+		const activationCmd = getActivationCommand(mode, apps);
+		if (activationCmd) {
+			const quote = (a) => JSON.stringify(a);
+			console.error(fmt.detail(`focus: ${activationCmd.bin} ${activationCmd.args.map(quote).join(" ")}`));
+		}
+	}
 	console.error("");
+	if (background) {
+		const logPath = join(tmpDir, "bx.log");
+		const logFd = openSync(logPath, "a", 384);
+		const child = spawn("sandbox-exec", [
+			"-f",
+			profilePath,
+			"-D",
+			`HOME=${HOME}`,
+			"-D",
+			`WORK=${workDirs[0]}`,
+			cmd.bin,
+			...cmd.args
+		], {
+			cwd: workDirs[0],
+			stdio: [
+				"ignore",
+				logFd,
+				logFd
+			],
+			detached: true,
+			env: {
+				...process$1.env,
+				CODEBOX_SANDBOX: "1"
+			}
+		});
+		child.unref();
+		bringAppToFront(mode, apps);
+		console.error(fmt.info(`running in background (pid ${child.pid})`));
+		console.error(fmt.detail(`log: ${logPath}`));
+		console.error(fmt.detail(`sandbox profile: ${profilePath} (kept until process exits)`));
+		process$1.exit(0);
+	}
 	const child = spawn("sandbox-exec", [
 		"-f",
 		profilePath,
@@ -1643,8 +1703,16 @@ async function main() {
 		}
 	});
 	bringAppToFront(mode, apps);
+	const cleanup = () => {
+		try {
+			rmSync(tmpDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	};
+	process$1.on("exit", cleanup);
 	child.on("close", (code) => {
-		rmSync(profilePath, { force: true });
 		process$1.exit(code ?? 0);
 	});
 }
@@ -1668,12 +1736,11 @@ function printPolicySummary(mode, workDirs, blockedDirs, ignoredPaths, readOnly)
 	if (extraIgnored > 0) parts.push(`${extraIgnored} from .bxignore`);
 	console.error(fmt.detail(parts.join(" · ")));
 }
-function printLaunchDetails(cmd, cwd, activationCmd) {
+function printLaunchDetails(cmd, cwd) {
 	const quote = (a) => JSON.stringify(a);
 	console.error(fmt.detail(`bin:  ${cmd.bin}`));
 	console.error(fmt.detail(`args: ${cmd.args.map(quote).join(" ") || "(none)"}`));
 	console.error(fmt.detail(`cwd:  ${cwd}`));
-	if (activationCmd) console.error(fmt.detail(`focus: ${activationCmd.bin} ${activationCmd.args.map(quote).join(" ")}`));
 }
 main();
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bx-mac",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "description": "Sandbox any macOS app — only your project directory stays accessible",
   "type": "module",
   "bin": {