Mudroom
Run coding agents in a Linux micro-VM on a clone of your project, then review and apply their changes like a pull request.
- Source repo
- Kernel-Hunter/mudroom
- Stars
- ★ 11
- Last updated
- today
- License
- MIT
- Primary language
- Swift
- FA score
- 78/100 · Good
At a glance
- How it runs
- Works with
- Portable with changesChatGPT · Codex · Claude Code · Claude.ai · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers on Apple-silicon Macs who want to turn off permission prompts and let Claude Code or Codex edit freely
- Not a fit if
- Teams that need host-local services on the Mac fully unreachable from the sandbox
- Linux desktop users who need a graphical review app
- Teams that need stable interfaces, not an early prototype with breaking changes
- Source review
- 78/100 · Good
What does this agent do, and when should you use it?
Mudroom is a sandbox runner for coding agents: it copy-on-write clones your project, runs Claude Code, Codex, Gemini CLI, opencode, Aider or any command inside a Linux micro-VM (or a Docker/Podman container), and never mounts your real folder. Network access defaults to Locked mode, where the VM can only reach a host-side proxy that enforces a per-project allowlist and writes every connection to network.jsonl. When the agent exits you read the diff in the macOS app or the CLI, apply everything, selected files or selected hunks, and undo any apply in one step. It is written in Swift and split into MudroomCore, the SwiftUI MudroomApp (macOS 26+) and the mudroom command; Apple-silicon Macs use Apple's container backend, other platforms use Docker or Podman. The project describes itself as an early prototype with expected rough edges and breaking changes.
mudroom new/run clones the project into sessions/<id>/base and work, picks a backend (apple running each container in its own lightweight VM, or docker/podman with the same image), mounts work/ at /workspace and launches the agent. During mudroom start a host HTTP proxy enforces the allowlist via HTTP_PROXY/HTTPS_PROXY, handles CONNECT, rejects loopback/private resolutions, caps request heads and connections, and logs host, port, bytes and duration to network.jsonl. While the agent runs, work/ is snapshotted every 5 minutes and once on exit, and mudroom diff --from/--to shows changes after any snapshot. mudroom diff compares base and work by content hash (never mtime) and prints M/A/D/P/L/T markers, binary notes, a collapsed .git line and ?/!/~ risk flags; mudroom hunks numbers hunks so mudroom apply last --all, path lists or --hunks 1,3 can apply them. Apply verifies the project still matches base, writes to a temp name then renames, records a rollback bundle, and mudroom undo restores it. Secrets reach the sandbox by environment name, with tokens kept in the macOS Keychain, 0600 files on Linux or Credential Manager on Windows.
- Developers on Apple-silicon Macs who want to turn off permission prompts and let Claude Code or Codex edit freely
- Review workflows that need per-hunk selection and one-step rollback before code lands in the real repo
- Teams worried about an agent uploading code or reaching intranet hosts, who want host-level allowlisting of egress
- Engineers on Linux or Windows adding an isolation layer around coding agents with Docker or Podman, reviewing through the CLI
- Projects that are not git repos or contain many untracked/ignored files that git-based review cannot cover
- Users who want local Ollama or LM Studio models callable from inside a locked-down sandbox
How do you install or deploy this agent?
On an Apple-silicon Mac running macOS 26 or later, use the install script or Homebrew; both clear the quarantine flag, and the script needs no sudo:
curl -fsSL https://raw.githubusercontent.com/Kernel-Hunter/mudroom/main/install.sh | shbrew install --cask kernel-hunter/tap/mudroomOn Windows, use Scoop or the release zip:
scoop bucket add kernel-hunter https://github.com/Kernel-Hunter/scoop-bucket
scoop install mudroomBuild from source (Xcode 26+ / Swift 6.2+):
git clone https://github.com/Kernel-Hunter/mudroom
cd mudroom
scripts/build-app.sh
open build/Mudroom.appCLI only (macOS or Linux):
swift build -c release
cp .build/release/mudroom /usr/local/bin/After installing you still must run Setup: install and start the VM runtime, build the agent image once (about 1.5 GB), check the VM network and sign in an agent.
How do you use this agent?
Run Setup on first launch, or unattended:
mudroom setup
mudroom setup --yes --no-sign-inSign in an agent and prepare the image:
mudroom agent login claude
mudroom image build --backend docker
mudroom network check --backend dockerStart a session, then review and apply:
mudroom run ~/code/myapp -- claude --dangerously-skip-permissions
mudroom diff last
mudroom hunks last src/parser.swift
mudroom apply last src/parser.swift --hunks 1,3
mudroom undo lastConfigure the allowlist and keys:
mudroom network allow registry.npmjs.org '*.githubusercontent.com'
mudroom network mode offline
mudroom keys set OPENROUTER_API_KEYIn the macOS app: New Session (⌘N) to pick folder, agent and network mode, the agent runs in Terminal.app, then Review's Files/Network/Timeline tabs drive Apply Selected (⌘↩), Apply All (⇧⌘↩) and Undo (⌥⌘Z).
What are this agent's strengths and limitations?
- Your real folder is never mounted: the session works on copy-on-write clones and changes only reach the project when you apply
- Fine-grained review: per file and per hunk apply, each apply recorded in a rollback bundle with one-step undo, and conflicts when you edited the same file yourself
- Locked mode routes the VM through a host proxy with a per-project allowlist, and
mudroom network checkprints auditable results for raw sockets, DNS and UDP that ignore the proxy - Ships both a SwiftUI desktop app and a CLI; Apple's container backend gives one VM per session on Apple silicon, Docker/Podman covers other platforms
- Handles untracked, ignored and non-git projects;
?,!and~flags mark unreadable entries and host-executed files that start unselected
- Self-described early prototype: expect rough edges and breaking changes
- The app needs macOS 26+ on Apple silicon; Linux and Windows get CLI only, with no graphical review UI
- With the apple backend the VM can still reach Mac services listening on all interfaces (e.g. port 7000); packet filtering is not available yet
- Tokens and keys sit in plain text in the runtime's config/inspect output while a session runs, and the Docker backend shares the Linux host kernel, a weaker boundary than a VM
- Locked mode depends on proxy variables, so tools that ignore them fail; allowed hosts are allowed completely because TLS is not inspected
- On Windows there are no Unix permission bits, NTFS clones are full copies, and signing in through the host's
claudeCLI is not implemented
How does this agent compare with similar options?
The README compares Mudroom against Docker Sandboxes (--clone mode), Apple's sandboxy containerization example, ArcBox and Claude Code's own sandboxing: Docker Sandboxes mounts your folder read-write by default and reviews through git; sandboxy shares the folder and writes land immediately; ArcBox mounts nothing but offers no review; Claude Code sandboxing applies OS-level limits to your real folder rather than a VM. Mudroom's differentiator is VM/clone isolation plus per-file and per-hunk apply with undo.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mudroom This agent | 78 · Good | Desktop appFree + model costs | ★ 11 | today | Swift | ChatGPT · Codex · Claude Code · Claude.ai · OpenAI API · Claude API |
| ABCA | 74 · Some gaps | Self-hosted serviceFree + model costs | ★ 161 | 3d ago | TypeScript | Claude Code |
| Concord MCP | 67 · Some gaps | — | ★ 558 | today | TypeScript | Codex · Claude Code |
| Pi Subagent | 65 · Some gaps | Agent plugin / skillFree + model costs | ★ 82 | 10d ago | JavaScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
README documents a strong sandbox design: the real folder is never mounted, a copy-on-write clone is used, Locked mode is default with host allowlisting, and every connection is logged; applying requires human diff review with partial apply and undo, so user confirmation and rollback are well handled. However, sensitive data handling has self-disclosed weaknesses: Apple container writes env vars in plaintext config.json mode 0644, Docker/Podman expose secrets via inspect, and opencode/Aider/custom commands receive all API keys — a known exposure, hence deduction. Dependency security shows only CI action pins (actions/checkout@v7) with no lockfile or vulnerability scanning evidence, scored 1. External effects: Open mode is unfiltered and unlogged, user-selectable but not default, scored 2. Source attribution is limited to README and LICENSE authorship with no verified publisher, scored 1.
README and CI are broadly consistent (macOS/Linux/Windows build and test, Windows sandbox end-to-end check), so self-consistency is fair; but the project self-describes as an early prototype and README version examples are inconsistent (0.1.1 vs 0.2.1), hence deduction. Dependency availability relies on Apple container 1.5+, Swift 6.2, Docker/Podman; documented but no offline or fallback path, scored 2. Failure messages: README cites Aider failing fast without a key and a Windows firewall hint (New-NetFirewallRule), concrete evidence, but error handling is not systematically described, scored 2.
Audience and scenarios cover the macOS app, Linux/Windows CLI, and multiple agents (Claude Code, Codex, Gemini, opencode, Aider, custom commands), well described. Capability boundaries clearly list the platform matrix, backend differences, and Open/Offline modes. Trigger precision: many CLI subcommands but no systematic description of argument conflicts or misuse handling, scored 2. Environment fit gives distinct install and build paths for Apple silicon, Intel, Linux, and Windows, fairly complete.
Information architecture is clear with a complete table of contents and sections; install notes cover curl, Homebrew, Scoop, and source builds in detail; examples and screenshots are rich. Naming stability is deducted for the early-prototype and breaking-changes declaration. Known limitations section exists but is truncated in the provided source, scored 2. License is MIT and complete. Versioning/changelog shows only a tag-based release workflow with no CHANGELOG, scored 1. Maintenance responsibility: publisher is unverified, only LICENSE names Karim Masmoudi, scored 1.
Output usability is high: diff review, per-file and per-hunk apply, undo, conflict detection, and network logs directly serve the review-then-apply workflow. Marginal value is clear: VM isolation and network allowlisting fill the safety gap left when agents run with permission prompts off. Cost-benefit: requires building a ~1.5GB image and depends on Apple container or Docker, with the full app only on macOS 26+, a high barrier, scored 2.
Most README claims map to CI workflows (build, test, Windows sandbox check, release checksums), giving some traceability; but key security claims (proxy only allows allowlisted hosts, secrets not on command line) lack test evidence in the visible files, scored 2. Cross-source corroboration is limited to README and CI, with LICENSE only supporting licensing, scored 2. Fact/inference separation: README labels the early-prototype status and distinguishes implemented features from limitations, but some statements (e.g., 'your real folder is never mounted') lack code-level support, scored 2.
- Publisher identity is unverified and the install script runs via curl | sh from the main branch, a supply-chain risk; pin a version and verify SHA-256.
- Apple container writes env vars in plaintext config.json mode 0644 and Docker/Podman expose secrets via inspect; opencode/Aider/custom commands receive all API keys, so use with care.
- Open network mode is entirely unfiltered and unlogged, risking data exfiltration; prefer the default Locked mode.
- The project self-describes as an early prototype with breaking changes, and README version examples are inconsistent.
- The full app is macOS 26+ Apple silicon only; other platforms are CLI and require Docker/Podman plus a ~1.5GB image build.
FAQ
Does Mudroom cost anything?
When do an agent's edits actually reach my project?
mudroom undo restores it; apply and undo refuse to run while the agent is still running.How strong is the network isolation?
mudroom network check probes DNS, IPv4, IPv6, UDP and proxy-bypassing sockets in a real sandbox. The README is explicit about the gaps: with the apple backend the VM can still reach Mac services bound to all interfaces, and Docker on Linux shares the host kernel.What can I run it on?
mudroom review, diff, hunks and apply --hunks for review. Windows also lacks Unix modes, full-copy clones on NTFS and host-side Claude sign-in.