linuxdevel · linuxdevel · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,5 @@ coverage/
 .turbo/
 bundle/
 .opencode/
+.worktrees/
+tmp/
diff --git a/AGENTS.md b/AGENTS.md
@@ -8,7 +8,7 @@ SafeClaw is an AI coding assistant with multi-provider LLM support (GitHub Copil
 
 The target user is an individual developer who wants AI-assisted coding with strong guarantees against prompt injection, malicious tool calls, and data exfiltration.
 
-**Linux-only. Node.js >= 22. pnpm 9+.**
+**Linux and macOS. Node.js >= 22. pnpm 9+.**
 
 ## Repository Structure
 
@@ -83,10 +83,10 @@ Each tool declares `requiredCapabilities` and implements a `ToolHandler` interfa
 `packages/core/src/tools/process-manager.ts` -- Tracks spawned child processes by UUID. Features: ring buffer output capture (1MB max per process), automatic cleanup after 1 hour, maximum 8 concurrent processes. Used by the `process` builtin tool.
 
 ### Sandbox
-- `packages/sandbox/src/sandbox.ts` -- Spawns child process with `unshare` + native helper
-- `packages/sandbox/src/policy-builder.ts` -- `PolicyBuilder` class with fluent API; `PolicyBuilder.forDevelopment(cwd, options?)` creates a development-ready policy with allowlisted system paths, compiler toolchains (JVM, GCC), an expanded ~120 syscall allowlist, and support for `extraExecutePaths`/`extraReadWritePaths` via `DevelopmentPolicyOptions`
+- `packages/sandbox/src/sandbox.ts` -- Wraps commands via `@anthropic-ai/sandbox-runtime` (`SandboxManager.wrapWithSandbox()`) as the outer layer; injects the C helper as the inner process via `--policy-file <tmp>` when found
+- `packages/sandbox/src/policy-builder.ts` -- `PolicyBuilder` class with fluent API; `PolicyBuilder.forDevelopment(cwd, options?)` creates a development-ready policy with allowlisted system paths, compiler toolchains (JVM, GCC), an expanded ~120 syscall allowlist, and support for `extraExecutePaths`/`extraReadWritePaths` via `DevelopmentPolicyOptions`; `PolicyBuilder.toRuntimeConfig(policy)` translates `SandboxPolicy` to `SandboxRuntimeConfig` for sandbox-runtime (write allowlist + credential dir denylist)
 - `native/src/main.c` -- C helper binary that applies: Landlock filesystem rules, seccomp-BPF syscall filtering, capability dropping, `PR_SET_NO_NEW_PRIVS`
-- Policy sent to helper via fd 3 as JSON
+- Policy sent to helper via `--policy-file <tmp>` (JSON written to a temp file at mode 0o600; cleaned up after each execution)
 
 ### Vault
 `packages/vault/src/vault.ts` -- AES-256-GCM encrypted JSON file store. Keys derived via scrypt from passphrase or fetched from OS keyring (GNOME `secret-tool`). File permissions enforced at 0o600.
@@ -114,7 +114,8 @@ Bootstrap flow (`packages/cli/src/commands/bootstrap.ts`):
 4. Load builtin skill manifest
 5. Read `brave_api_key` from vault; if present, include web_search tool in tool registry
 6. Create ProcessManager for background process tracking
-7. Create: CapabilityRegistry -> CapabilityEnforcer -> ToolRegistry -> Sandbox -> ToolOrchestrator -> ContextCompactor -> Agent
+7. Initialize `SandboxManager` network proxy (via `PolicyBuilder.toRuntimeConfig()`)
+8. Create: CapabilityRegistry -> CapabilityEnforcer -> ToolRegistry -> Sandbox -> ToolOrchestrator -> ContextCompactor -> Agent
 8. Return `{ agent, sessionManager, capabilityRegistry, auditLog }`
 
 CLI commands: `chat` (default), `onboard`, `audit`, `serve`/`server`, `doctor`, `help`, `version`

diff --git a/README.md b/README.md
@@ -12,15 +12,15 @@ SafeClaw is a secure AI coding assistant with mandatory OS-level sandboxing, sig
 curl -fsSL https://raw.githubusercontent.com/linuxdevel/safeclaw/main/install.sh | bash
 ```
 
-Requires: Linux (x86\_64 or arm64), Node.js >= 22, bubblewrap (`apt install bubblewrap`).
+Requires: Linux (x86\_64 or arm64) or macOS, Node.js >= 22, bubblewrap (`apt install bubblewrap`), socat (`apt install socat`).
 
 After install, run `safeclaw onboard` for first-time setup.
 
 ## Features
 
 ### Security
 
-- Zero-trust security model with mandatory OS-level sandboxing — bubblewrap `pivot_root` filesystem isolation (outer) + Landlock + seccomp-BPF + capability dropping (inner), Linux namespaces (PID, net, mount, IPC, UTS)
+- Zero-trust security model with mandatory OS-level sandboxing — `@anthropic-ai/sandbox-runtime` outer layer (bubblewrap `pivot_root` + bind mounts on Linux; sandbox-exec on macOS) + C helper inner layer (Landlock + seccomp-BPF + capability dropping on Linux). Supports Linux and macOS.
 - Development-ready sandbox policy via `PolicyBuilder.forDevelopment()` — allows compilers (GCC, JVM), package managers, and standard dev tools while enforcing kernel-level access control. Selective home directory binding hides `~/.ssh`, `~/.aws`, `~/.gnupg` structurally.
 - AES-256-GCM encrypted secrets vault with OS keyring or passphrase-derived keys
 - Ed25519-signed skill manifests with capability declarations and runtime enforcement
@@ -69,7 +69,7 @@ Planned features in implementation order:
 | 2 | Automatic context compaction | [plan](docs/plans/2026-03-05-context-compaction.md) | High |
 | 3 | Streaming UX (Phase 1 — readline) | [plan](docs/plans/2026-03-05-streaming-ux.md) | High |
 | 4 | Better CLI/TUI (Ink-based) | [plan](docs/plans/2026-03-05-tui.md) | High |
-| 5 | Bubblewrap sandbox (`pivot_root` isolation) | [design](docs/plans/2026-03-07-bubblewrap-sandbox-design.md) · [plan](docs/plans/2026-03-07-bubblewrap-sandbox-implementation.md) | High |
+| 5 | Sandbox-runtime integration (`pivot_root` + macOS support) | [design](docs/plans/2026-03-07-bubblewrap-sandbox-design.md) · [plan](docs/plans/2026-03-20-sandbox-runtime-integration.md) | **Done** |
 | 6 | Parallel agents | [plan](docs/plans/2026-03-05-parallel-agents.md) | Medium |
 | 7 | Long-running background agents | [plan](docs/plans/2026-03-05-background-agents.md) | Medium |
 | 8 | Superpowers skill integration | [plan](docs/plans/2026-03-05-superpowers-integration.md) | Medium |
@@ -93,7 +93,7 @@ Planned features in implementation order:
 Monorepo structure:
 
 - `@safeclaw/vault` — Encrypted secrets storage
-- `@safeclaw/sandbox` — OS-level process sandboxing with bubblewrap (`pivot_root`) + C helper (Landlock/seccomp) and `PolicyBuilder` for development-ready policies
+- `@safeclaw/sandbox` — OS-level process sandboxing: outer layer via `@anthropic-ai/sandbox-runtime` (bwrap on Linux, sandbox-exec on macOS), inner layer via C helper (Landlock + seccomp-BPF + cap-drop). `PolicyBuilder` for development-ready policies; `PolicyBuilder.toRuntimeConfig()` translates policies for sandbox-runtime.
 - `@safeclaw/core` — Capabilities, agent runtime, sessions, tools, skills, model providers, copilot client
 - `@safeclaw/gateway` — HTTP server with auth and rate limiting
 - `@safeclaw/cli` — Command-line interface

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -74,9 +74,10 @@ OS-level process isolation using Linux kernel features.
 
 - `SandboxPolicy` / `DEFAULT_POLICY`: policy types with maximally restrictive defaults
 - `PolicyBuilder`: fluent API for constructing sandbox policies; `PolicyBuilder.forDevelopment(cwd)` creates a ready-made policy for software development with allowlisted system paths, compiler toolchains, and an expanded syscall set
-- `detectKernelCapabilities`: probes `/proc` for Landlock, seccomp, namespace support
+- `detectKernelCapabilities`: probes `/proc` for Landlock, seccomp, namespace support; also detects bubblewrap availability
 - `assertSandboxSupported`: throws if required kernel features are missing
-- `Sandbox` class: executes commands under policy (stub in v1; types and policies are real)
+- `Sandbox` class: executes commands by wrapping via `SandboxManager.wrapWithSandbox()` (outer layer) and injecting the C helper as the inner process via `--policy-file` when found
+- `PolicyBuilder.toRuntimeConfig()`: translates `SandboxPolicy` to `SandboxRuntimeConfig` for sandbox-runtime (write allowlist, credential dir denylist, network domains)
 
 No dependencies on other SafeClaw packages.
 
@@ -148,7 +149,7 @@ Command-line interface adapter.
 - `runOnboarding`: five-step onboarding wizard (kernel check, auth, vault, signing key, model selection)
 - `setupChat`: wires the CLI adapter to the agent
 - `runAudit`: generates security audit reports (text or JSON)
-- `runDoctor`: runs 12 diagnostic checks across system, security, config, and connectivity categories
+- `runDoctor`: runs diagnostic checks across system (platform, bwrap, socat, rg, helper binary), security (Landlock, seccomp, namespaces), config, and connectivity categories
 
 Dependencies: `@safeclaw/core`, `@safeclaw/gateway`, `@safeclaw/sandbox`, `@safeclaw/vault`.
 
@@ -294,9 +295,9 @@ The audit log maintains the last N entries in memory (default: 100). The `safecl
 
 ## Key design decisions
 
-### Linux-only (v1)
+### Linux and macOS
 
-SafeClaw v1 targets Linux exclusively. The sandboxing architecture depends on Landlock (kernel >= 5.13), seccomp-BPF, and Linux namespaces. These have no direct equivalents on macOS or Windows. Future versions may add platform-specific sandboxing.
+SafeClaw supports Linux and macOS. On Linux, the full stack is available: bubblewrap `pivot_root` container (via `@anthropic-ai/sandbox-runtime`) + Landlock + seccomp-BPF + capability dropping (via C helper). On macOS, the outer `sandbox-exec` layer is used; the C helper and Linux-specific enforcement (Landlock, seccomp, namespaces) are not active. Windows is not supported.
 
 ### Multi-provider LLM support
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -4,26 +4,34 @@
 
 - **Node.js** >= 22.0.0
 - **pnpm** >= 9.0.0
-- **Linux** with kernel >= 5.13 (required for Landlock, seccomp-BPF, and namespaces)
+- **Linux** with kernel >= 5.13 (required for Landlock, seccomp-BPF, and namespaces), **or macOS** (uses sandbox-exec for outer isolation; C helper not available on macOS)
+- **bubblewrap** (`apt install bubblewrap` on Debian/Ubuntu) — required on Linux for `pivot_root` filesystem isolation
+- **socat** (`apt install socat` on Debian/Ubuntu) — required by `@anthropic-ai/sandbox-runtime` for network proxy
 - **GNOME Keyring** (`secret-tool`) if using OS keyring for vault encryption (optional; passphrase fallback available)
 - A **GitHub account** with Copilot access (for default Copilot provider), or an **OpenAI** or **Anthropic** API key
 
-### Verifying kernel support
+### Verifying sandbox support
 
-SafeClaw requires mandatory sandboxing. Check that your kernel supports the necessary features:
+Run `safeclaw doctor` after installation to verify all dependencies. To manually check:
 
 ```bash
-# Kernel version (must be >= 5.13)
+# bubblewrap (Linux)
+which bwrap && bwrap --version
+
+# socat (network proxy)
+which socat
+
+# Kernel version (Linux, must be >= 5.13 for Landlock)
 uname -r
 
-# Seccomp support
+# Seccomp support (Linux)
 grep Seccomp /proc/self/status
 
-# Namespace support
+# Namespace support (Linux)
 ls /proc/self/ns/{user,pid,net,mnt}
 ```
 
-All four namespaces (user, PID, net, mount) must be available. If any are missing, SafeClaw will warn during onboarding and sandbox isolation will be limited.
+All four namespaces (user, PID, net, mount) must be available on Linux. If any are missing, SafeClaw will warn during onboarding and sandbox isolation will be limited. On macOS, namespace-based isolation is replaced by sandbox-exec.
 
 ## Installation
 
@@ -209,8 +217,8 @@ Run diagnostic checks to verify your SafeClaw installation:
 safeclaw doctor
 ```
 
-The doctor command runs 12 checks across four categories:
-- **System**: Node.js version, native helper binary, disk space
+The doctor command runs checks across four categories:
+- **System**: Node.js version, platform support, bubblewrap (`bwrap`), native helper binary, socat, ripgrep (`rg`), disk space
 - **Security**: Landlock, seccomp, namespace support
 - **Config**: vault accessibility, signing key, default model
 - **Connectivity**: GitHub Copilot API reachability
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,3 +9,5 @@ coverage/ @@
     .turbo/
     bundle/
     .opencode/
+    .worktrees/
+    tmp/