RunHaven

Caution

Pre-release: v0.5.0, CLI-complete. The latest cut is a pre-1.0, CLI-only pre-release. This checkout includes an unreleased terminal UI over the same planner, run records, diagnostics, and run-control cores. The desktop app remains alpha. Container and image layouts, run-record formats, provider allowlists, auth-broker behavior, TUI behavior, desktop behavior, and --json outputs may still change before a stable release.

RunHaven is a Rust CLI with an unreleased terminal UI and an alpha Tauri/Svelte desktop shell for running Claude Code, Codex, Gemini, Antigravity, Copilot, or custom coding agents inside Apple container on macOS 26+ (Apple silicon only). It does not replace those tools. It gives them a repeatable local boundary so the secure way to run an agent is also the easy way.

It is built for people who sign in to their coding agent with a subscription or OAuth account (Claude Pro/Max, ChatGPT, a Google account, GitHub), not only with API keys. Signing in is one command and is reused across runs, and your host login is never read or mounted.

Current Surfaces

Surface	Status	Use it for
CLI	v0.5.0 pre-release, complete for the current command contract	Automation, explicit commands, recovery, diagnostics, and the stable backend for every UI.
Terminal UI	Active Codex-vendored TUI, unreleased	A bare interactive runhaven opens the RunHaven TUI for workspace choice, agent choice, network/auth policy changes, plan review, typed launch confirmation, foreground launch handoff, active-run summaries, typed run control, confirmation-gated log snapshots, confirmation-gated run diff review, run history, diagnostics, and post-run recovery.
Desktop app	Alpha scaffold	Typed setup, launch, status, bounded logs, run control, and diagnostics. More maintenance and worktree flows remain CLI-first.

Why RunHaven

AI coding agents can inspect a project, edit files, run commands, and iterate fast. That same power is risky when the agent runs directly on your Mac with ambient access to your home directory, shell environment, SSH keys, cloud credentials, browser profiles, and unrelated repositories. RunHaven puts each run inside a bounded sandbox.

Risk or need	RunHaven answer
Broad host access	Mounts one selected workspace at /workspace, not your whole home directory or credential folders.
Ambient credentials	Does not mount raw SSH keys, browser profiles, cloud credential folders, provider login caches, or arbitrary environment variables by default.
Unclear execution	runhaven plan prints the workspace, state volume, network mode, egress status, preflight, and Apple container run command before execution.
Repeated sign-in	runhaven login <agent> signs in once and reuses isolated agent state across runs. Claude uses an explicit host setup-token flow; RunHaven never reads your ~/.claude.json, macOS Keychain, or browser profiles.
Network sprawl	Uses a secure profile-aware default: provider allowlist where the agent's hosts are bundled, otherwise internet. Local-only internal and explicit --network overrides remain available.
Risky edits	--worktree runs in a RunHaven-owned git worktree you can diff, keep, recover, merge, or discard.
Local cleanup	RunHaven-owned images, volumes, networks, runs, egress logs, and auth-broker state have explicit inspection and cleanup commands.

RunHaven is not a complete data-loss or exfiltration solution. The selected agent can still read the mounted workspace and its isolated home volume, and internet mode is not domain-restricted. See the security model for the full boundary.

Quick start

Start Apple container, then install RunHaven from this checkout:

container system start
cargo install --path . --locked

Run the non-mutating setup guide:

runhaven setup

Build an agent image and sign in once:

runhaven image build claude
runhaven login claude

From the project directory you want the agent to work on, inspect the plan and run:

runhaven plan claude
runhaven run claude

Or open the terminal UI on an interactive terminal:

runhaven

The TUI is an unreleased RunHaven-only checkpoint over the same Rust backend. It opens with a launch flow, shows the exact command and safety facts before launch, requires typed confirmation for lower-security plans, restores the terminal before starting the agent, and includes active-run summaries, typed stop/hard-stop/repair controls, confirmation-gated log snapshots, confirmation-gated run diff review, run history, preflight diagnostics, and post-run recovery. It does not replace the CLI: subcommands, pipes, and redirected invocations still use the CLI directly.

Use the smallest project directory the agent needs. RunHaven mounts that directory at /workspace, not your whole home directory. See Installation for requirements and Usage for command-level workflows.

Signing in

RunHaven never reads your host login state. You sign in once, the credential lives in an isolated per-agent home volume (or, for Claude, host-side and injected at run time), and every later run reuses it.

Agent	Sign in with	How it works
Claude	runhaven login claude	Runs Anthropic's claude setup-token on your host (needs Claude Code installed). The token is injected into the sandbox at run time, never written to ~/.claude and never placed on a command line.
Codex	runhaven login codex	codex login --device-auth inside the sandbox. Enable device-code login in ChatGPT under Settings then Security.
Gemini	Isolated in-sandbox login, or API-key broker	Google account OAuth is kept inside the isolated Gemini state volume. Headless API-key runs can use --api-key-broker-env GEMINI_API_KEY.
Copilot	runhaven login copilot	The GitHub device flow inside the sandbox. Answer y when it offers to store the token; the file lands in the isolated volume, not on your Mac.
Antigravity	runhaven login antigravity	Starts agy; approve the Google sign-in in your browser, then type /exit.

Each login persists in a per-agent home volume reused across projects (--auth-scope agent, the default), or pass --auth-scope project to keep it to one workspace. Clear a login with runhaven login <agent> --clear.

Prefer API keys? A host-side broker keeps the real key on the host and gives the guest only a placeholder plus a base-URL redirect (runhaven run codex --api-key-broker-env OPENAI_API_KEY). See the auth broker doc.

Network and egress

RunHaven has three network modes:

Mode	Use it for	Behavior
provider	Normal hosted-agent use when provider hosts are bundled.	Managed internal network plus a host-side allowlist proxy for the agent's provider hosts.
internal	Local-only analysis or tests.	Host-only Apple container network with no internet egress.
internet	Package managers, registries, CDNs, or custom images that need broad internet.	Unrestricted outbound access.

When you omit --network, RunHaven chooses provider for profiles with bundled provider hosts and internet for profiles without them. In provider mode, each agent ships a small maintained allowlist, including narrow domain-family patterns where needed. If something is blocked, RunHaven says so in plain language and the per-host detail is in runhaven egress log.

Review and recovery

RunHaven records bounded run metadata without prompts, tokens, environment values, or file contents, and gives every owned resource an explicit review or cleanup path:

runhaven runs active
runhaven runs status <run-id>
runhaven runs logs-follow <run-id>
runhaven runs stop <run-id>
runhaven runs kill <run-id>
runhaven runs repair <run-id>
runhaven runs list
runhaven runs show <run-id>
runhaven runs log <run-id>
runhaven runs diff <run-id>
runhaven runs merge <run-id>
runhaven runs discard <run-id>
runhaven state list
runhaven network list
runhaven image doctor

The current TUI exposes active-run summaries, typed stop/hard-stop/repair controls, bounded log snapshots only after you type logs, run history without host workspace paths, run diff review only after you type diff, preflight checks, secret-free diagnostics, and post-run recovery over the same validated cores. Worktree merge/discard, image rebuild, state cleanup, and network cleanup remain CLI-first today.

Status and roadmap

RunHaven is alpha/pre-release. v0.5.0 is the CLI-only pre-release already cut. This checkout now contains the unreleased RunHaven-only TUI checkpoint as a first-class reference over the same CLI backend. The Tauri/Svelte desktop shell is alpha: it can read setup, dashboard, profile, folder-pick, and run-plan state and supports confirmed launch, image readiness, sanitized live status, bounded output snapshots, stop, kill, repair, and secret-free diagnostics. Image build, state cleanup, network cleanup, and worktree review remain CLI-first.

The roadmap now treats the CLI as the complete technical surface, the TUI as a hardened terminal checkpoint, and the desktop app as the future easiest path (full detail in ROADMAP.md and the release plan):

• v0.5.0, CLI complete: the command set, docs, JSON and local-data decisions, runtime smokes, profile support tiers, diagnostics, cleanup, and security boundaries are finished and verified for the CLI-only pre-release.
• Runtime and security hardening: completed slices are recorded in the roadmap and state files; keep runtime evidence current when the boundary is touched.
• Hardened terminal checkpoint: a bare interactive runhaven opens the four-step launch wizard and run manager over the shared planner and policy. Keep it focused on the workflow and boundary checks that harden the backend.
• Remaining non-UI scope and CLI public release: promote one design-first item at a time without weakening CLI semantics or default safety.
• First-class desktop app, next: the native macOS app becomes the easiest safe path for nontechnical users, signed and notarized. Its release version label is open.

Product rule

The secure path must be the easy path: secure defaults are the shortest workflow, supported lower-security choices warn and require explicit intent, and unsupported, invalid, or hard-boundary violations fail closed. Apple container machine is not the default boundary; explicit or user-managed machine workflows are warned, not blocked solely for being less secure.

Documentation

Use the smallest doc that matches the question:

Need	Start here
Install and run	Installation, Capabilities, Usage
Sign-in and credentials	Auth broker, Provider endpoints
Security and runtime boundary	Security model, Apple Container gap analysis
Architecture and research	Architecture, Research
Terminal UI	TUI build plan, TUI architecture, TUI brand graphics
Desktop UI	Tauri UI guardrails, Tauri log viewing design, Tauri UI research plan
Release planning	Roadmap, v0.5.0 release plan, Release gap analysis, CLI surface coverage, Pinning policy
Project operations	Harness, Contributing, Security policy

Development

Agent-assisted work starts from three files only: AGENTS.md, feature_list.json, and current-state.md. Load the harness docs only when a task touches that surface.

Use the smallest relevant check for a change:

cargo fmt --check
cargo test --locked
cargo clippy --all-targets -- -D warnings
cargo run --locked --bin runhaven-check-pins
npm --prefix ui run check
npm --prefix ui test
npm --prefix ui run test:e2e
git diff --check

Full local harness verification is ./init.sh. Opt-in Apple container runtime smokes are scripts/apple_container_smoke.sh (add --with-provider for the egress checks). Docs-only changes use the docs checks from the verification matrix; runtime, security-boundary, image, or install-flow changes need focused tests plus the relevant Apple container smokes.

License

MIT