From 7cefd5ce7bb9b9a7892b1cb5685ca78998eb17ae Mon Sep 17 00:00:00 2001
From: Karim Masmoudi <125830216+Kernel-Hunter@users.noreply.github.com>
Date: Fri, 30 Oct 2026 19:31:07 +0100
Subject: [PATCH 1/5] Redesign the README
Centered header with badges and the demo, a feature grid, a mermaid
diagram, install per platform, a quick start and a comparison table up
front. The reference sections keep all their content, with the longest
parts in collapsible blocks, plus an FAQ, contributing notes and a star
history chart.
---
README.md | 536 +++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 450 insertions(+), 86 deletions(-)
diff --git a/README.md b/README.md
index 832a304..49674b3 100644
--- a/README.md
+++ b/README.md
@@ -1,87 +1,174 @@
+
+
+
+
# Mudroom
-Run coding agents in a sandbox, then review their changes like a pull request
-before anything touches your project.
+**Run coding agents in a sandbox, then review their changes like a pull request.**
+Mudroom runs Claude Code, Codex, Gemini CLI, opencode, Aider or any command on a clone of your
+project in a Linux micro-VM, behind a network allowlist. Nothing reaches your folder until you apply it.
+
+[](https://github.com/Kernel-Hunter/mudroom/releases/latest)
+[](https://github.com/Kernel-Hunter/mudroom/releases)
+[](https://github.com/Kernel-Hunter/mudroom/stargazers)
+[](LICENSE)
+
+[](#install)
+[](#requirements)
+[](https://github.com/Kernel-Hunter/mudroom/actions/workflows/ci.yml)
+
+[Website](https://kernel-hunter.github.io/mudroom/) ·
+[Download](https://github.com/Kernel-Hunter/mudroom/releases/latest) ·
+[Docs](#documentation) ·
+[Report a bug](https://github.com/Kernel-Hunter/mudroom/issues/new)
+
+
+
+
+
+
+
+
Coding agents work best with permission prompts turned off, and that means
they can delete files or reach any host while you aren't looking. Mudroom
-runs Claude Code, Codex, Gemini CLI, opencode, Aider (or any command) in a
-Linux micro-VM, on a copy-on-write clone of your project, with network access
-limited to the hosts you allow. Your real folder is never mounted. When the
-agent is done you read the diff, apply all of it, some files, some hunks or
-none, and undo any apply later.
+gives each run a disposable copy-on-write clone of your project inside a
+Linux micro-VM, with network access limited to the hosts you allow. Your real
+folder is never mounted. When the agent is done you read the diff like a pull
+request, apply all of it, some files, some hunks or none, and undo any apply
+later.
-macOS app and CLI on Apple-silicon Macs. CLI only (with Docker or Podman) on
-Linux, Windows and Intel Macs.
+> **Status:** early prototype. Expect rough edges and breaking changes.
-> Status: early prototype. Expect rough edges and breaking changes.
+
+Watch the video
-
+
https://github.com/user-attachments/assets/ff599cbc-fbd9-4c8f-801d-fd2e52ccb0c6
-## Quick start
+
-1. Install (Apple-silicon Mac, macOS 26 or later):
+## What you get
- ```sh
- curl -fsSL https://raw.githubusercontent.com/Kernel-Hunter/mudroom/main/install.sh | sh
- ```
+
+
+
- Or with Homebrew: `brew install --cask kernel-hunter/tap/mudroom`
+**Your folder stays untouched**
+The agent edits a copy-on-write clone (APFS, or a reflink on btrfs and XFS),
+untracked and ignored files included. Your project is never mounted.
- On Windows (CLI only), see [Install on Windows](#install-on-windows).
+
+
-2. Open Mudroom and work through the Setup window: install and start the VM
- runtime, build the agent image (a few minutes, once), and sign in an
- agent. `mudroom setup` does the same in a terminal.
+**A VM per session**
+Apple's `container` boots one lightweight Linux VM for each session. Docker
+and Podman work too, with gVisor or Kata if you have them.
-3. Click New Session, pick a folder and an agent, and start. When the agent
- finishes, review the diff in Mudroom and apply what you want.
+
+
+
+
-## Contents
+**Network allowlist**
+Locked by default: no DNS and no route out. The only exit is a proxy on your
+machine that lets through the agent's API hosts plus the ones you add.
-- [Requirements](#requirements)
-- [Install](#install)
-- [Setup](#setup)
-- [The app](#the-app)
-- [Command line](#command-line)
-- [Agents, sign-in and API keys](#agents-sign-in-and-api-keys)
-- [Keep files out of the sandbox](#keep-files-out-of-the-sandbox)
-- [Network](#network)
-- [Review and apply](#review-and-apply)
-- [Docker and Podman](#docker-and-podman)
-- [How it works](#how-it-works)
-- [How it compares](#how-it-compares)
-- [Limitations](#limitations)
-- [Development](#development)
+
+
-## Requirements
+**A log of every connection**
+In locked mode: host, port, bytes, allowed or blocked, and which program in
+the sandbox opened it (`git-remote-https`, `node`, `python3`).
-| Platform | What you get | Sandbox backend |
-|---|---|---|
-| macOS 26+, Apple silicon | App and CLI | `apple` (Apple's `container`, one VM per session), or `docker`/`podman` |
-| macOS 26+, Intel | CLI only (build from source) | `docker` or `podman` |
-| Linux x86_64 and arm64 | CLI only (build from source) | `docker` or `podman` |
-| Windows 10/11, x86_64 and arm64 | CLI only ([release zip](#install-on-windows) or build from source) | `docker` (Docker Desktop) or `podman` (Podman machine) |
+
+
+
+
-The `apple` backend needs Apple's [`container`](https://github.com/apple/container)
-CLI, version 1.5 or later. Setup installs it with Homebrew if you don't have
-it.
+**Keys stay out**
+`.env` files, `*.pem`, SSH keys and `.netrc` are left out of the agent's
+copy by default. Edit the list per project or with a `.mudroomignore`.
-The CLI picks a backend with `--backend apple|docker|podman|auto` (or
-`MUDROOM_BACKEND`). `auto`, the default, uses Apple's `container` on an
-Apple-silicon Mac with macOS 26+ where it is installed, otherwise Docker,
-otherwise Podman. A session remembers its backend, so `mudroom start` uses
-the same one again. See [Docker and Podman](#docker-and-podman) for how
-isolation differs from the VM backend.
+
+
+
+**Review like a pull request**
+Files grouped by change, unified or side-by-side diffs, a checkbox per file
+and per hunk. Your own edits since the start are flagged, never overwritten.
+
+
+
+
+
+
+**Undo and snapshots**
+Any apply can be undone in one step, even one killed halfway. Snapshots
+taken every 5 minutes show what changed after any point.
+
+
+
+
+**Any agent, your sign-in**
+Five agents set up for you, or any command. Sign in with your Claude account,
+the ChatGPT and Google logins you already have, API keys, or local models.
+
+
+
+
+
+## How it works
+
+```mermaid
+flowchart LR
+ P["Your project"] -->|"copy-on-write clone"| W["Session copy"]
+ W -->|"mounted at /workspace"| A
+ subgraph VM["Linux micro-VM or container"]
+ A["Coding agent"]
+ end
+ A -->|"only way out"| X["Allowlist proxy"]
+ X -->|"allowed hosts"| N(("Internet"))
+ W --> R["Diff review"]
+ R -->|"apply what you pick"| P
+ R -.->|"undo"| P
+```
+
+1. Mudroom clones the project twice: `base/` is the starting point and `work/`
+ is what the agent edits. On APFS the clones take no extra disk until files
+ change.
+2. The agent runs in its own VM (or container) with only `work/` inside. In
+ locked mode its one way out is the proxy, which checks every host against
+ the project's allowlist and logs the connection.
+3. You review `base/` against `work/` in the app or the terminal and apply
+ what you pick. Mudroom checks that each file in your project still matches
+ `base/`, so your own edits are never overwritten. Any apply can be undone.
+
+More detail in [Under the hood](#under-the-hood), [Network](#network) and
+[Review and apply](#review-and-apply).
## Install
+### macOS
+
+Apple silicon, macOS 26 or later. App and CLI. With Homebrew, which also
+installs Apple's `container` CLI:
+
+```sh
+brew install --cask kernel-hunter/tap/mudroom
+```
+
+Or with the install script:
+
```sh
curl -fsSL https://raw.githubusercontent.com/Kernel-Hunter/mudroom/main/install.sh | sh
```
+
+What the install script does, and how to uninstall
+
+
+
The script needs macOS 26 or later on Apple silicon. It downloads the latest
release, checks its SHA-256 when the release publishes one, puts Mudroom.app
in /Applications (or ~/Applications if /Applications isn't writable) and
@@ -93,27 +180,38 @@ version. To remove Mudroom (your sessions and settings stay):
curl -fsSL https://raw.githubusercontent.com/Kernel-Hunter/mudroom/main/install.sh | sh -s -- --uninstall
```
-Or with Homebrew, which also installs Apple's `container` CLI:
+
-```sh
-brew install --cask kernel-hunter/tap/mudroom
-```
+
+About signing and Gatekeeper
+
+
Mudroom is ad-hoc signed, not notarized. The install script and the Homebrew
cask remove the quarantine flag, so macOS opens it. If you download the zip
in a browser, use System Settings > Privacy & Security > Open Anyway, or run
`xattr -dr com.apple.quarantine /Applications/Mudroom.app`.
+
+
+On an Intel Mac, the CLI works with Docker or Podman; [build it from
+source](#build-from-source).
+
### Install on Windows
-With [Scoop](https://scoop.sh):
+CLI only, Windows 10/11 on x86_64 or arm64. With [Scoop](https://scoop.sh):
```powershell
scoop bucket add kernel-hunter https://github.com/Kernel-Hunter/scoop-bucket
scoop install mudroom
```
-Without Scoop: each release has a zip for x86_64 and one for arm64:
+
+Without Scoop: install from the release zip
+
+
+
+Each release has a zip for x86_64 and one for arm64:
`mudroom--windows-x86_64.zip` and `mudroom--windows-arm64.zip`
on the [Releases](https://github.com/Kernel-Hunter/mudroom/releases/latest)
page, each with a `.sha256`. The zip holds a folder with `mudroom.exe` and
@@ -138,8 +236,11 @@ To upgrade, run the same lines with the new version, without the PATH
line. `mudroom.exe` isn't code-signed; if Windows blocks it after you unzip
with Explorer, run `Get-ChildItem $dir | Unblock-File`.
+
+
The Scoop and winget manifests are in [packaging/scoop](packaging/scoop)
-and [packaging/winget](packaging/winget).
+and [packaging/winget](packaging/winget). The winget package is waiting for
+review in the winget repository, so `winget install` doesn't find it yet.
Then install a container runtime: [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/)
with the WSL 2 backend (Linux containers, the default), or
@@ -155,6 +256,21 @@ mudroom network check --backend docker
Run `mudroom` from Windows Terminal or any console with VT support. See
[Windows](#windows-1) for what is different from macOS and Linux.
+### Linux
+
+CLI only, x86_64 and arm64, built from source. You need Swift 6.2 or later
+([swift.org/install](https://www.swift.org/install/)) and Docker Engine or
+Podman:
+
+```sh
+git clone https://github.com/Kernel-Hunter/mudroom
+cd mudroom
+swift build -c release
+cp .build/release/mudroom /usr/local/bin/ # or anywhere on your PATH
+mudroom image build --backend docker # or --backend podman, once
+mudroom network check --backend docker # see what the sandbox can reach
+```
+
### Build from source
You need Xcode 26+ (Swift 6.2+).
@@ -173,13 +289,8 @@ swift build -c release
cp .build/release/mudroom /usr/local/bin/ # or anywhere on your PATH
```
-On Linux you need Swift 6.2 or later ([swift.org/install](https://www.swift.org/install/))
-and Docker Engine or Podman. Then build the agent image once:
-
-```sh
-mudroom image build --backend docker # or --backend podman
-mudroom network check --backend docker # see what the sandbox can reach
-```
+On Linux you also need Docker Engine or Podman and the agent image; see
+[Linux](#linux).
#### Windows
@@ -202,6 +313,109 @@ headers then refuse to build swift-crypto's BoringSSL. Run `mudroom` from
Windows Terminal or any console with VT support (Windows 10 1809 or later).
See [Windows](#windows-1) for what is different there.
+## Quick start
+
+In the app:
+
+1. Open Mudroom and work through the Setup window: install and start the VM
+ runtime, build the agent image (a few minutes, once), and sign in an
+ agent.
+2. Click New Session, pick a folder and an agent, and start.
+3. When the agent finishes, review the diff in Mudroom and apply what you
+ want.
+
+From a terminal. On Linux and Windows the same commands use Docker, or
+Podman when Docker isn't there; `--backend` picks one.
+
+```sh
+# Once: start the VM runtime, build the agent image, sign in an agent
+mudroom setup
+
+# Run an agent on a clone of your project
+mudroom run ~/code/myapp -- claude --dangerously-skip-permissions
+
+# Read the diff, pick files or hunks, press x to apply
+mudroom review last
+
+# See what the agent connected to, and what was blocked
+mudroom network log last
+
+# Changed your mind
+mudroom undo last
+```
+
+## How it compares
+
+How the usual ways of running an agent differ, in their default setup:
+
+| | Agent on your machine | Dev container | Cloud sandbox | Mudroom |
+|---|---|---|---|---|
+| Where the agent edits | Your real folder | Your folder, usually bind-mounted | A copy on the provider's servers | A clone; your folder is never mounted |
+| When edits reach your folder | Right away | Right away | When you pull or download them | When you apply them |
+| Boundary | Your user account, plus the agent's own prompts or sandbox | A container (the host's kernel on Linux) | The provider's VM or container | One micro-VM per session, or a container with Docker or Podman |
+| Network | Anything your machine reaches, unless the agent's own sandbox limits it | Open by default | Depends on the provider | Allowlist through a proxy (locked mode, the default), each connection logged with the command that opened it |
+| Review | `git diff`, or per-edit prompts | `git diff` | Through git or the provider's tools | Review app or terminal screen, per file and per hunk, with undo |
+| Your code leaves your machine | Only what the agent sends | Only what the agent sends | Yes, it runs remotely | Only what the agent sends to allowed hosts |
+| Account or bill for the sandbox | None | None | A provider account, usually paid by usage | None, MIT |
+
+A dev container gives you a reproducible toolchain, and a cloud sandbox runs
+many agents in parallel without using your machine. Mudroom does neither: it
+runs on your own computer, the review app needs a Mac with macOS 26, and the
+agent image is one general-purpose image unless you pass your own with
+`--image`.
+
+### Other agent sandboxes
+
+Checked against each project's docs on 2026-09-30. Corrections welcome.
+
+| | Where the agent works | When its writes reach your folder | Review before they land |
+|---|---|---|---|
+| Mudroom | Linux micro-VM, on an APFS clone; your folder is never mounted | When you apply | Diff app, per file and per hunk, with undo |
+| [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/security/) | microVM; your folder mounted read-write by default, or a private git clone with `--clone` | Right away by default; with `--clone`, when you fetch | Through git, in clone mode |
+| [Apple's `sandboxy` example](https://github.com/apple/containerization/tree/main/examples/sandboxy) | Linux VM with your folder shared in | Right away | No |
+| [ArcBox](https://github.com/arcboxlabs/arcbox/blob/master/docs/agent-sandbox.md) | microVM with nothing mounted | Only what you copy out | No |
+| [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing) | Your real folder, with OS-level limits (no VM) | Right away | Per-edit prompts, unless you skip permissions |
+
+If your project is a git repo and you're happy reviewing with git, Docker Sandboxes' `--clone` mode gets you close. Mudroom also covers untracked and ignored files and folders that aren't repos, and gives you a review screen and per-apply undo.
+
+
+
+## Documentation
+
+- [Requirements](#requirements)
+- [Setup](#setup)
+- [The app](#the-app)
+- [Command line](#command-line)
+- [Agents, sign-in and API keys](#agents-sign-in-and-api-keys)
+- [Keep files out of the sandbox](#keep-files-out-of-the-sandbox)
+- [Network](#network)
+- [Review and apply](#review-and-apply)
+- [Docker and Podman](#docker-and-podman)
+- [Under the hood](#under-the-hood)
+- [Limitations](#limitations)
+- [FAQ](#faq)
+- [Development](#development)
+
+## Requirements
+
+| Platform | What you get | Sandbox backend |
+|---|---|---|
+| macOS 26+, Apple silicon | App and CLI | `apple` (Apple's `container`, one VM per session), or `docker`/`podman` |
+| macOS 26+, Intel | CLI only (build from source) | `docker` or `podman` |
+| Linux x86_64 and arm64 | CLI only (build from source) | `docker` or `podman` |
+| Windows 10/11, x86_64 and arm64 | CLI only ([release zip](#install-on-windows) or build from source) | `docker` (Docker Desktop) or `podman` (Podman machine) |
+
+The `apple` backend needs Apple's [`container`](https://github.com/apple/container)
+CLI, version 1.5 or later. Setup installs it with Homebrew if you don't have
+it.
+
+The CLI picks a backend with `--backend apple|docker|podman|auto` (or
+`MUDROOM_BACKEND`). `auto`, the default, uses Apple's `container` on an
+Apple-silicon Mac with macOS 26+ where it is installed, otherwise Docker,
+otherwise Podman. A session remembers its backend, so `mudroom start` uses
+the same one again. See [Docker and Podman](#docker-and-podman) for how
+isolation differs from the VM backend.
+
## Setup
The Setup window opens on the first launch. It has four steps:
@@ -223,7 +437,7 @@ Mudroom > Setup, and the sidebar tells you when a step needs attention. If
the VM runtime stops later (after a reboot, say), starting a session starts
it again.
-
+
In a terminal:
@@ -277,7 +491,12 @@ to date.
The review app is macOS only. Elsewhere, `mudroom review ` is a
terminal review screen: toggle files, read diffs, pick single hunks and apply
-the selection. Its keys:
+the selection.
+
+
+Keys in mudroom review
+
+
- File list: up/down or j/k move, space toggles a file, a toggles all, enter
opens the file, x applies the selection after a y/N prompt, q quits.
@@ -290,6 +509,8 @@ the selection. Its keys:
4 MB) open as a plain diff and are applied whole: up/down scroll, space/b
page, q back.
+
+
Whole files and selected hunks go into the project in one apply, so one
`mudroom undo` takes all of it back. `mudroom diff`, `hunks` and `apply` do
the same from scripts.
@@ -432,6 +653,11 @@ mudroom agent login gemini # Gemini CLI's own sign-in screen
mudroom agent status # signed in or not, per agent
```
+
+How the sign-in link gets out of the sandbox
+
+
+
Copying a sign-in link out of a terminal is fragile: it wraps over several
lines, and losing the end gives errors such as "Invalid
code_challenge_method". So each run sets `BROWSER` in the sandbox to a small
@@ -446,6 +672,8 @@ the rest of the request (PKCE challenge, state) unchanged. After signing in,
paste the code back: in Setup into the code field, in a terminal where the
prompt is (the agent's prompt doesn't echo it).
+
+
### Agent config directories
Each agent gets its own config directory,
@@ -591,6 +819,11 @@ Like the network commands, these work on the current directory, or take
of the sandbox" section that shows what the chosen folder would leave out
and lets you add and remove patterns.
+
+Pattern syntax
+
+
+
Patterns use `.gitignore` syntax, relative to the project root:
- `name` matches a file or folder with that name at any depth. `/name` and
@@ -609,6 +842,8 @@ Patterns use `.gitignore` syntax, relative to the project root:
`.ENV` is caught too: on a default APFS or NTFS disk it is the same file as
`.env`. On Windows, trailing dots and spaces are ignored as well.
+
+
A `.mudroomignore` file at the project root, in the same syntax, adds
patterns for everyone who uses the project, and can be committed. It can only
add: a `!` line in it takes back a pattern from the same file, never one from
@@ -720,7 +955,12 @@ the pid (`pid`) and the command lines of its parents up to the agent
(`parents`, nearest first). The app shows the command in the connection list,
with the parents in its tooltip, and the programs under each host.
-How it works: a small bash script, the watcher, runs inside the VM next to
+
+How the connection watcher works
+
+
+
+A small bash script, the watcher, runs inside the VM next to
the agent. It reads TCP's connection counter in `/proc/net/snmp` every 100 ms
(every 20 ms for a second after a connection opens), and when it changed,
looks in `/proc/net/tcp` and `tcp6` for new connections to the proxy. It finds
@@ -741,6 +981,8 @@ user, and the forwarder container passes each client's source port to the
proxy in a PROXY protocol line. The image needs bash (Mudroom's has it);
without it the log simply has no commands.
+
+
Limits:
- It is informational, not a security boundary. The allowlist is decided on
@@ -956,6 +1198,11 @@ Networks:
listens on 127.0.0.1, which Docker Desktop forwards `host.docker.internal`
to.
+
+Network check output with Docker
+
+
+
`mudroom network check --backend docker`, locked mode, gave this on Docker
Desktop (engine 29.8) on macOS 27, and the same apart from addresses on
Docker Engine 29.1 on Ubuntu 24.04 arm64 (run nested in a privileged
@@ -978,6 +1225,8 @@ has no host address, so services on the host aren't reachable, and no
firewall inside the container is needed. (This output is from before the
check opened a port of its own; it now probes that port instead of 7000.)
+
+
### How strong is the isolation
A container is not a VM. On Linux, Docker and Podman containers share the
@@ -1069,7 +1318,7 @@ on it. What is different from macOS and Linux:
`host.containers.internal` doesn't lead to Windows, and locked mode
can't work.
-## How it works
+## Under the hood
```
~/Library/Application Support/Mudroom/ (Linux: ~/.local/share/mudroom/, Windows: %LOCALAPPDATA%\Mudroom\)
@@ -1123,20 +1372,6 @@ container in its own lightweight VM, and one to `docker` or `podman`. The
proxy is plain BSD sockets (Winsock on Windows), so it runs the same on
macOS, Linux and Windows.
-## How it compares
-
-Checked against each project's docs on 2026-09-30. Corrections welcome.
-
-| | Where the agent works | When its writes reach your folder | Review before they land |
-|---|---|---|---|
-| Mudroom | Linux micro-VM, on an APFS clone; your folder is never mounted | When you apply | Diff app, per file and per hunk, with undo |
-| [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/security/) | microVM; your folder mounted read-write by default, or a private git clone with `--clone` | Right away by default; with `--clone`, when you fetch | Through git, in clone mode |
-| [Apple's `sandboxy` example](https://github.com/apple/containerization/tree/main/examples/sandboxy) | Linux VM with your folder shared in | Right away | No |
-| [ArcBox](https://github.com/arcboxlabs/arcbox/blob/master/docs/agent-sandbox.md) | microVM with nothing mounted | Only what you copy out | No |
-| [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing) | Your real folder, with OS-level limits (no VM) | Right away | Per-edit prompts, unless you skip permissions |
-
-If your project is a git repo and you're happy reviewing with git, Docker Sandboxes' `--clone` mode gets you close. Mudroom also covers untracked and ignored files and folders that aren't repos, and gives you a review screen and per-apply undo.
-
## Limitations
- **With the apple backend, the Mac's own services are blocked by a firewall
@@ -1182,6 +1417,115 @@ If your project is a git repo and you're happy reviewing with git, Docker Sandbo
- The app is ad-hoc signed, not notarized. See [Install](#install) for what
that means when you download it.
+## FAQ
+
+
+Does the agent ever touch my real project folder?
+
+
+
+No. The agent edits `work/`, a clone in Mudroom's own data folder, and your
+project is never mounted into the sandbox. Files change in your project only
+when you apply them, and each apply can be undone. See [How apply stays
+safe](#how-apply-stays-safe).
+
+
+
+
+What if I edit a file while the agent is working?
+
+
+
+Apply checks each file in your project against the session's starting copy.
+A file you changed is reported as a conflict and left alone; the rest still
+applies.
+
+
+
+
+Can the agent read my .env or SSH keys?
+
+
+
+Not by default. `.env` files, `*.pem`, `*.key`, SSH private keys and `.netrc`
+are left out of the agent's copy. The list matches names, not contents, so a
+key pasted into another file is still copied. See [Keep files out of the
+sandbox](#keep-files-out-of-the-sandbox).
+
+
+
+
+Do I need an API key?
+
+
+
+Not for Claude Code, Codex or Gemini CLI: Mudroom can use your Claude
+account, or the ChatGPT and Google logins you already have. opencode, Aider
+and custom commands need a provider key (OpenRouter works for most models)
+or local models through Ollama or LM Studio. See [Agents, sign-in and API
+keys](#agents-sign-in-and-api-keys).
+
+
+
+
+Can I use it on Linux or Windows?
+
+
+
+Yes, as a CLI with Docker or Podman. There is no review app there:
+`mudroom review` is a terminal review screen with per-file and per-hunk
+selection. On Linux a container shares the host's kernel, so the isolation
+is weaker than the VM backend on a Mac. See [How strong is the
+isolation](#how-strong-is-the-isolation).
+
+
+
+
+Why does the agent run in Terminal and not inside the app?
+
+
+
+Agents are interactive terminal programs and you often need to answer them,
+so the app opens each session in Terminal.app and follows its progress
+through `session.json`.
+
+
+
+
+How much disk does a session use?
+
+
+
+On APFS the clones take no extra disk until files change. The agent image
+is about 1.5 GB, built once. If the project is on a disk that can't clone,
+Mudroom falls back to plain copies.
+
+
+
+
+Is the network log a security boundary?
+
+
+
+No. The allowlist is enforced by the proxy on your machine. The note about
+which command opened each connection comes from a watcher inside the VM, and
+a hostile agent can mislead it. See [Which process made each
+connection](#which-process-made-each-connection).
+
+
+
+
+macOS says Mudroom can't be opened. What now?
+
+
+
+Mudroom is ad-hoc signed, not notarized. The Homebrew cask and the install
+script remove the quarantine flag for you. For a zip downloaded in a browser,
+use System Settings > Privacy & Security > Open Anyway, or run
+`xattr -dr com.apple.quarantine /Applications/Mudroom.app`.
+
+
+
## Development
```sh
@@ -1212,8 +1556,28 @@ The proxy tests run it against a loopback test server. The app target is
platforms). `MudroomCore` has no UI code; the app and the CLI both sit on
top of it.
+## Contributing
+
+Bug reports, corrections to the comparison tables and pull requests are
+welcome. Open an [issue](https://github.com/Kernel-Hunter/mudroom/issues) for
+a bug or an idea. For code, `swift build` and `swift test` run without a VM on
+macOS, Linux and Windows (see [Development](#development)), and
+`mudroom network check` tests isolation on a real sandbox.
+
+If Mudroom is useful to you, a star helps other people find it.
+
## License
MIT. See [LICENSE](LICENSE).
Built by [Karim Masmoudi](https://github.com/Kernel-Hunter). My other projects are at [karimmasmoudi.vercel.app](https://karimmasmoudi.vercel.app/projects/).
+
+## Star history
+
+
+
+
+
+
+
+
From dd5367db6b88031cbb0a881a8091d707c12cb444 Mon Sep 17 00:00:00 2001
From: Karim Masmoudi <125830216+Kernel-Hunter@users.noreply.github.com>
Date: Fri, 30 Oct 2026 19:33:38 +0100
Subject: [PATCH 2/5] Use the lowercase repo name for the star history chart
---
README.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
index 49674b3..434c2ae 100644
--- a/README.md
+++ b/README.md
@@ -1576,8 +1576,8 @@ Built by [Karim Masmoudi](https://github.com/Kernel-Hunter). My other projects a
-
-
-
+
+
+
From 44fa445a43bfe60edfb11cab8abfb55c917e7d45 Mon Sep 17 00:00:00 2001
From: Karim Masmoudi <125830216+Kernel-Hunter@users.noreply.github.com>
Date: Fri, 30 Oct 2026 19:35:47 +0100
Subject: [PATCH 3/5] README: say the clone leaves .env files and keys out
---
README.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 434c2ae..2b5a54a 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,8 @@ https://github.com/user-attachments/assets/ff599cbc-fbd9-4c8f-801d-fd2e52ccb0c6
**Your folder stays untouched**
The agent edits a copy-on-write clone (APFS, or a reflink on btrfs and XFS),
-untracked and ignored files included. Your project is never mounted.
+untracked and ignored files included, minus `.env` files and keys. Your
+project is never mounted.
From 591d89ed05d7eda42954b6adfaa9b83c5c3d5d11 Mon Sep 17 00:00:00 2001
From: Karim Masmoudi <125830216+Kernel-Hunter@users.noreply.github.com>
Date: Fri, 30 Oct 2026 20:53:11 +0100
Subject: [PATCH 4/5] README: themed banner, short header, install first
Replace the icon and for-the-badge header with a light and dark banner,
a link row and two flat badges. Put the overview video and the install
steps in the first screen, show the main features with screenshots, and
turn wide tables into lists so the page reads on a phone. Drop the star
history chart. Every section anchor stays the same.
---
README.md | 565 +++++++++++++++------------
docs/assets/mudroom-banner-dark.png | Bin 0 -> 220095 bytes
docs/assets/mudroom-banner-light.png | Bin 0 -> 255941 bytes
3 files changed, 311 insertions(+), 254 deletions(-)
create mode 100644 docs/assets/mudroom-banner-dark.png
create mode 100644 docs/assets/mudroom-banner-light.png
diff --git a/README.md b/README.md
index 2b5a54a..ab757aa 100644
--- a/README.md
+++ b/README.md
@@ -1,159 +1,42 @@
-
-
-
-
-# Mudroom
-
-**Run coding agents in a sandbox, then review their changes like a pull request.**
-Mudroom runs Claude Code, Codex, Gemini CLI, opencode, Aider or any command on a clone of your
-project in a Linux micro-VM, behind a network allowlist. Nothing reaches your folder until you apply it.
-
-[](https://github.com/Kernel-Hunter/mudroom/releases/latest)
-[](https://github.com/Kernel-Hunter/mudroom/releases)
-[](https://github.com/Kernel-Hunter/mudroom/stargazers)
-[](LICENSE)
-
-[](#install)
-[](#requirements)
-[](https://github.com/Kernel-Hunter/mudroom/actions/workflows/ci.yml)
-
-[Website](https://kernel-hunter.github.io/mudroom/) ·
-[Download](https://github.com/Kernel-Hunter/mudroom/releases/latest) ·
-[Docs](#documentation) ·
-[Report a bug](https://github.com/Kernel-Hunter/mudroom/issues/new)
-
-
-
-
-
-
-
-
-
-Coding agents work best with permission prompts turned off, and that means
-they can delete files or reach any host while you aren't looking. Mudroom
-gives each run a disposable copy-on-write clone of your project inside a
-Linux micro-VM, with network access limited to the hosts you allow. Your real
-folder is never mounted. When the agent is done you read the diff like a pull
-request, apply all of it, some files, some hunks or none, and undo any apply
-later.
-
-> **Status:** early prototype. Expect rough edges and breaking changes.
-
-
-Watch the video
-
-
+
+
+
+
+
+
+
+**Mudroom** runs coding agents like Claude Code, Codex, Gemini CLI, opencode
+and Aider (or any command) on a clone of your project, inside a Linux
+micro-VM, with network access limited to the hosts you allow. When the agent
+is done, you review its changes like a pull request, apply all of it, some
+files, some hunks or none, and undo any apply later. It's a free, local
+alternative to cloud agent sandboxes, and your real folder is never mounted.
https://github.com/user-attachments/assets/ff599cbc-fbd9-4c8f-801d-fd2e52ccb0c6
-
-
-## What you get
-
-
-
-
-
-**Your folder stays untouched**
-The agent edits a copy-on-write clone (APFS, or a reflink on btrfs and XFS),
-untracked and ignored files included, minus `.env` files and keys. Your
-project is never mounted.
-
-
-
-
-**A VM per session**
-Apple's `container` boots one lightweight Linux VM for each session. Docker
-and Podman work too, with gVisor or Kata if you have them.
-
-
-
-
-
-
-**Network allowlist**
-Locked by default: no DNS and no route out. The only exit is a proxy on your
-machine that lets through the agent's API hosts plus the ones you add.
-
-
-
-
-**A log of every connection**
-In locked mode: host, port, bytes, allowed or blocked, and which program in
-the sandbox opened it (`git-remote-https`, `node`, `python3`).
-
-
-
-
-
-
-**Keys stay out**
-`.env` files, `*.pem`, SSH keys and `.netrc` are left out of the agent's
-copy by default. Edit the list per project or with a `.mudroomignore`.
-
-
-
-
-**Review like a pull request**
-Files grouped by change, unified or side-by-side diffs, a checkbox per file
-and per hunk. Your own edits since the start are flagged, never overwritten.
-
-
-
-
-
-
-**Undo and snapshots**
-Any apply can be undone in one step, even one killed halfway. Snapshots
-taken every 5 minutes show what changed after any point.
-
-
-
-
-**Any agent, your sign-in**
-Five agents set up for you, or any command. Sign in with your Claude account,
-the ChatGPT and Google logins you already have, API keys, or local models.
-
-
-
-
-
-## How it works
-
-```mermaid
-flowchart LR
- P["Your project"] -->|"copy-on-write clone"| W["Session copy"]
- W -->|"mounted at /workspace"| A
- subgraph VM["Linux micro-VM or container"]
- A["Coding agent"]
- end
- A -->|"only way out"| X["Allowlist proxy"]
- X -->|"allowed hosts"| N(("Internet"))
- W --> R["Diff review"]
- R -->|"apply what you pick"| P
- R -.->|"undo"| P
-```
-
-1. Mudroom clones the project twice: `base/` is the starting point and `work/`
- is what the agent edits. On APFS the clones take no extra disk until files
- change.
-2. The agent runs in its own VM (or container) with only `work/` inside. In
- locked mode its one way out is the proxy, which checks every host against
- the project's allowlist and logs the connection.
-3. You review `base/` against `work/` in the app or the terminal and apply
- what you pick. Mudroom checks that each file in your project still matches
- `base/`, so your own edits are never overwritten. Any apply can be undone.
+
33 seconds, with sound: the agent edits a clone in a VM, reaches only the hosts you allow, and you apply what you pick.
-More detail in [Under the hood](#under-the-hood), [Network](#network) and
-[Review and apply](#review-and-apply).
+> **Status:** early prototype. Expect rough edges and breaking changes.
## Install
+The Mac app and CLI run on Apple-silicon Macs with macOS 26 or later. On
+Linux, Windows and Intel Macs, Mudroom is a CLI that uses Docker or Podman.
+
### macOS
-Apple silicon, macOS 26 or later. App and CLI. With Homebrew, which also
-installs Apple's `container` CLI:
+With Homebrew, which also installs Apple's `container` CLI:
```sh
brew install --cask kernel-hunter/tap/mudroom
@@ -207,6 +90,20 @@ scoop bucket add kernel-hunter https://github.com/Kernel-Hunter/scoop-bucket
scoop install mudroom
```
+Then install a container runtime: [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/)
+with the WSL 2 backend (Linux containers, the default), or
+[Podman](https://podman.io/docs/installation#windows) with a Podman machine
+(`podman machine init`, then `podman machine start`). Build the agent image
+once and check the network:
+
+```powershell
+mudroom image build --backend docker # or --backend podman
+mudroom network check --backend docker
+```
+
+Run `mudroom` from Windows Terminal or any console with VT support. See
+[Windows](#windows-1) for what is different from macOS and Linux.
+
Without Scoop: install from the release zip
@@ -237,82 +134,33 @@ To upgrade, run the same lines with the new version, without the PATH
line. `mudroom.exe` isn't code-signed; if Windows blocks it after you unzip
with Explorer, run `Get-ChildItem $dir | Unblock-File`.
-
-
The Scoop and winget manifests are in [packaging/scoop](packaging/scoop)
and [packaging/winget](packaging/winget). The winget package is waiting for
review in the winget repository, so `winget install` doesn't find it yet.
-Then install a container runtime: [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/)
-with the WSL 2 backend (Linux containers, the default), or
-[Podman](https://podman.io/docs/installation#windows) with a Podman machine
-(`podman machine init`, then `podman machine start`). Build the agent image
-once and check the network:
-
-```powershell
-mudroom image build --backend docker # or --backend podman
-mudroom network check --backend docker
-```
-
-Run `mudroom` from Windows Terminal or any console with VT support. See
-[Windows](#windows-1) for what is different from macOS and Linux.
+
### Linux
CLI only, x86_64 and arm64, built from source. You need Swift 6.2 or later
([swift.org/install](https://www.swift.org/install/)) and Docker Engine or
-Podman:
-
-```sh
-git clone https://github.com/Kernel-Hunter/mudroom
-cd mudroom
-swift build -c release
-cp .build/release/mudroom /usr/local/bin/ # or anywhere on your PATH
-mudroom image build --backend docker # or --backend podman, once
-mudroom network check --backend docker # see what the sandbox can reach
-```
+Podman.
-### Build from source
+
+Build and install the CLI
-You need Xcode 26+ (Swift 6.2+).
+
```sh
git clone https://github.com/Kernel-Hunter/mudroom
cd mudroom
-scripts/build-app.sh # build/Mudroom.app (app + bundled CLI), ad-hoc signed
-open build/Mudroom.app
-```
-
-For the command line only (macOS or Linux):
-
-```sh
swift build -c release
cp .build/release/mudroom /usr/local/bin/ # or anywhere on your PATH
+mudroom image build --backend docker # or --backend podman, once
+mudroom network check --backend docker # see what the sandbox can reach
```
-On Linux you also need Docker Engine or Podman and the agent image; see
-[Linux](#linux).
-
-#### Windows
-
-You need Swift 6.2 or later for Windows ([swift.org/install/windows](https://www.swift.org/install/windows/)),
-which brings the Visual Studio build tools it needs, and Docker Desktop
-(WSL 2 backend, Linux containers) or Podman Desktop with a Podman machine.
-In a Developer PowerShell:
-
-```powershell
-git clone https://github.com/Kernel-Hunter/mudroom
-cd mudroom
-swift build -c release -Xcxx -D_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH
-copy .build\release\mudroom.exe $env:LOCALAPPDATA\Microsoft\WindowsApps\ # or anywhere on your PATH
-mudroom image build --backend docker
-```
-
-The `-Xcxx` flag is only needed when your Visual Studio is newer than the
-Clang in your Swift toolchain (Visual Studio 2026 with Swift 6.2): the C++
-headers then refuse to build swift-crypto's BoringSSL. Run `mudroom` from
-Windows Terminal or any console with VT support (Windows 10 1809 or later).
-See [Windows](#windows-1) for what is different there.
+
## Quick start
@@ -345,19 +193,133 @@ mudroom network log last
mudroom undo last
```
+## Features
+
+Coding agents work best with permission prompts turned off, and that means
+they can delete files or reach any host while you aren't looking. Mudroom
+puts a sandbox and a review step between the agent and your project.
+
+- **Your folder stays untouched.** The agent edits a copy-on-write clone
+ (APFS, or a reflink on btrfs and XFS), untracked and ignored files
+ included, minus `.env` files and keys. Your project is never mounted.
+- **A VM per session.** Apple's `container` boots one lightweight Linux VM
+ for each session. Docker and Podman work too, with gVisor or Kata if you
+ have them.
+- **Network allowlist.** Locked by default: no DNS and no route out. The
+ only exit is a proxy on your machine that lets through the agent's API
+ hosts plus the ones you add.
+- **A log of every connection.** In locked mode: host, port, bytes, allowed
+ or blocked, and which program in the sandbox opened it
+ (`git-remote-https`, `node`, `python3`).
+- **Keys stay out.** `.env` files, `*.pem`, SSH keys and `.netrc` are left
+ out of the agent's copy by default. Edit the list per project or with a
+ `.mudroomignore`.
+- **Review like a pull request.** Files grouped by change, unified or
+ side-by-side diffs, a checkbox per file and per hunk. Your own edits since
+ the start are flagged, never overwritten.
+- **Undo and snapshots.** Any apply can be undone in one step, even one
+ killed halfway. Snapshots taken every 5 minutes show what changed after
+ any point.
+- **Any agent, your sign-in.** Five agents set up for you, or any command.
+ Sign in with your Claude account, the ChatGPT and Google logins you
+ already have, API keys, or local models.
+
+### Pick what to keep, file by file or hunk by hunk
+
+Changed files are grouped into Added, Modified, Deleted and Mode & Type,
+each with a checkbox, next to a unified or side-by-side diff. Modified text
+files have a checkbox per hunk, so you can take some edits and leave others.
+
+
+
+
+
+
+### See every host the agent tried to reach
+
+The Network tab lists blocked hosts first, with bytes and connection
+counts. Allow adds a blocked host to the project's allowlist for the next
+session.
+
+
+
+
+
+
+### Your own edits are never overwritten
+
+Files you changed yourself since the session started are flagged in the
+list and above the diff. Apply leaves them alone and takes the rest.
+
+
+
+### Look back at any point in the run
+
+Snapshots are taken while the agent works. Move the timeline slider and the
+file list shows only what changed after that point.
+
+
+
## How it compares
How the usual ways of running an agent differ, in their default setup:
-| | Agent on your machine | Dev container | Cloud sandbox | Mudroom |
-|---|---|---|---|---|
-| Where the agent edits | Your real folder | Your folder, usually bind-mounted | A copy on the provider's servers | A clone; your folder is never mounted |
-| When edits reach your folder | Right away | Right away | When you pull or download them | When you apply them |
-| Boundary | Your user account, plus the agent's own prompts or sandbox | A container (the host's kernel on Linux) | The provider's VM or container | One micro-VM per session, or a container with Docker or Podman |
-| Network | Anything your machine reaches, unless the agent's own sandbox limits it | Open by default | Depends on the provider | Allowlist through a proxy (locked mode, the default), each connection logged with the command that opened it |
-| Review | `git diff`, or per-edit prompts | `git diff` | Through git or the provider's tools | Review app or terminal screen, per file and per hunk, with undo |
-| Your code leaves your machine | Only what the agent sends | Only what the agent sends | Yes, it runs remotely | Only what the agent sends to allowed hosts |
-| Account or bill for the sandbox | None | None | A provider account, usually paid by usage | None, MIT |
+| | Edits reach your folder | Network |
+|---|---|---|
+| Agent on your machine | Right away | Anything your machine reaches |
+| Dev container | Right away | Open by default |
+| Cloud sandbox | When you pull them | Depends on the provider |
+| **Mudroom** | **When you apply them** | **Allowlist, each connection logged** |
+
+
+The full comparison
+
+
+
+**Agent on your machine**
+
+- Where it edits: your real folder, and edits land right away.
+- Boundary: your user account, plus the agent's own prompts or sandbox.
+- Network: anything your machine reaches, unless the agent's own sandbox
+ limits it.
+- Review: `git diff`, or per-edit prompts.
+- Your code leaves your machine: only what the agent sends.
+- Account or bill for the sandbox: none.
+
+**Dev container**
+
+- Where it edits: your folder, usually bind-mounted, and edits land right
+ away.
+- Boundary: a container (the host's kernel on Linux).
+- Network: open by default.
+- Review: `git diff`.
+- Your code leaves your machine: only what the agent sends.
+- Account or bill for the sandbox: none.
+
+**Cloud sandbox**
+
+- Where it edits: a copy on the provider's servers. Edits reach your folder
+ when you pull or download them.
+- Boundary: the provider's VM or container.
+- Network: depends on the provider.
+- Review: through git or the provider's tools.
+- Your code leaves your machine: yes, it runs remotely.
+- Account or bill for the sandbox: a provider account, usually paid by
+ usage.
+
+**Mudroom**
+
+- Where it edits: a clone; your folder is never mounted. Edits reach your
+ folder when you apply them.
+- Boundary: one micro-VM per session, or a container with Docker or Podman.
+- Network: allowlist through a proxy (locked mode, the default), each
+ connection logged with the command that opened it.
+- Review: review app or terminal screen, per file and per hunk, with undo.
+- Your code leaves your machine: only what the agent sends to allowed
+ hosts.
+- Account or bill for the sandbox: none, MIT.
+
+
A dev container gives you a reproducible toolchain, and a cloud sandbox runs
many agents in parallel without using your machine. Mudroom does neither: it
@@ -369,42 +331,88 @@ agent image is one general-purpose image unless you pass your own with
Checked against each project's docs on 2026-09-30. Corrections welcome.
-| | Where the agent works | When its writes reach your folder | Review before they land |
-|---|---|---|---|
-| Mudroom | Linux micro-VM, on an APFS clone; your folder is never mounted | When you apply | Diff app, per file and per hunk, with undo |
-| [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/security/) | microVM; your folder mounted read-write by default, or a private git clone with `--clone` | Right away by default; with `--clone`, when you fetch | Through git, in clone mode |
-| [Apple's `sandboxy` example](https://github.com/apple/containerization/tree/main/examples/sandboxy) | Linux VM with your folder shared in | Right away | No |
-| [ArcBox](https://github.com/arcboxlabs/arcbox/blob/master/docs/agent-sandbox.md) | microVM with nothing mounted | Only what you copy out | No |
-| [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing) | Your real folder, with OS-level limits (no VM) | Right away | Per-edit prompts, unless you skip permissions |
+- **Mudroom.** Linux micro-VM, on an APFS clone; your folder is never
+ mounted. The agent's writes reach your folder when you apply them, after
+ a diff review per file and per hunk, with undo.
+- **[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/security/).**
+ A microVM, with your folder mounted read-write by default, or a private
+ git clone with `--clone`. Writes reach your folder right away by default;
+ with `--clone`, when you fetch. Review goes through git, in clone mode.
+- **[Apple's `sandboxy` example](https://github.com/apple/containerization/tree/main/examples/sandboxy).**
+ A Linux VM with your folder shared in. Writes land right away, with no
+ review step.
+- **[ArcBox](https://github.com/arcboxlabs/arcbox/blob/master/docs/agent-sandbox.md).**
+ A microVM with nothing mounted. Only what you copy out reaches your
+ folder, with no review step.
+- **[Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing).**
+ Your real folder, with OS-level limits (no VM). Writes land right away,
+ with per-edit prompts unless you skip permissions.
+
+If your project is a git repo and you're happy reviewing with git, Docker
+Sandboxes' `--clone` mode gets you close. Mudroom also covers untracked and
+ignored files and folders that aren't repos, and gives you a review screen
+and per-apply undo.
+
+## How it works
+
+```mermaid
+flowchart LR
+ P["Your project"] -->|"copy-on-write clone"| W["Session copy"]
+ W -->|"mounted at /workspace"| A
+ subgraph VM["Linux micro-VM or container"]
+ A["Coding agent"]
+ end
+ A -->|"only way out"| X["Allowlist proxy"]
+ X -->|"allowed hosts"| N(("Internet"))
+ W --> R["Diff review"]
+ R -->|"apply what you pick"| P
+ R -.->|"undo"| P
+```
-If your project is a git repo and you're happy reviewing with git, Docker Sandboxes' `--clone` mode gets you close. Mudroom also covers untracked and ignored files and folders that aren't repos, and gives you a review screen and per-apply undo.
+1. Mudroom clones the project twice: `base/` is the starting point and `work/`
+ is what the agent edits. On APFS the clones take no extra disk until files
+ change.
+2. The agent runs in its own VM (or container) with only `work/` inside. In
+ locked mode its one way out is the proxy, which checks every host against
+ the project's allowlist and logs the connection.
+3. You review `base/` against `work/` in the app or the terminal and apply
+ what you pick. Mudroom checks that each file in your project still matches
+ `base/`, so your own edits are never overwritten. Any apply can be undone.
+
+More detail in [Under the hood](#under-the-hood), [Network](#network) and
+[Review and apply](#review-and-apply).
## Documentation
-- [Requirements](#requirements)
-- [Setup](#setup)
-- [The app](#the-app)
-- [Command line](#command-line)
-- [Agents, sign-in and API keys](#agents-sign-in-and-api-keys)
-- [Keep files out of the sandbox](#keep-files-out-of-the-sandbox)
-- [Network](#network)
-- [Review and apply](#review-and-apply)
-- [Docker and Podman](#docker-and-podman)
-- [Under the hood](#under-the-hood)
-- [Limitations](#limitations)
-- [FAQ](#faq)
-- [Development](#development)
+The rest of this page is the full reference:
+[Requirements](#requirements) ·
+[Build from source](#build-from-source) ·
+[Setup](#setup) ·
+[The app](#the-app) ·
+[Command line](#command-line) ·
+[Agents, sign-in and API keys](#agents-sign-in-and-api-keys) ·
+[Keep files out of the sandbox](#keep-files-out-of-the-sandbox) ·
+[Network](#network) ·
+[Review and apply](#review-and-apply) ·
+[Docker and Podman](#docker-and-podman) ·
+[Under the hood](#under-the-hood) ·
+[Limitations](#limitations) ·
+[FAQ](#faq) ·
+[Development](#development)
## Requirements
-| Platform | What you get | Sandbox backend |
-|---|---|---|
-| macOS 26+, Apple silicon | App and CLI | `apple` (Apple's `container`, one VM per session), or `docker`/`podman` |
-| macOS 26+, Intel | CLI only (build from source) | `docker` or `podman` |
-| Linux x86_64 and arm64 | CLI only (build from source) | `docker` or `podman` |
-| Windows 10/11, x86_64 and arm64 | CLI only ([release zip](#install-on-windows) or build from source) | `docker` (Docker Desktop) or `podman` (Podman machine) |
+- **macOS 26+, Apple silicon:** app and CLI. Sandbox backend `apple`
+ (Apple's `container`, one VM per session), or `docker`/`podman`.
+- **macOS 26+, Intel:** CLI only (build from source), with `docker` or
+ `podman`.
+- **Linux x86_64 and arm64:** CLI only (build from source), with `docker`
+ or `podman`.
+- **Windows 10/11, x86_64 and arm64:** CLI only ([release
+ zip](#install-on-windows) or build from source), with `docker` (Docker
+ Desktop) or `podman` (Podman machine).
The `apple` backend needs Apple's [`container`](https://github.com/apple/container)
CLI, version 1.5 or later. Setup installs it with Homebrew if you don't have
@@ -417,6 +425,48 @@ otherwise Podman. A session remembers its backend, so `mudroom start` uses
the same one again. See [Docker and Podman](#docker-and-podman) for how
isolation differs from the VM backend.
+### Build from source
+
+You need Xcode 26+ (Swift 6.2+).
+
+```sh
+git clone https://github.com/Kernel-Hunter/mudroom
+cd mudroom
+scripts/build-app.sh # build/Mudroom.app (app + bundled CLI), ad-hoc signed
+open build/Mudroom.app
+```
+
+For the command line only (macOS or Linux):
+
+```sh
+swift build -c release
+cp .build/release/mudroom /usr/local/bin/ # or anywhere on your PATH
+```
+
+On Linux you also need Docker Engine or Podman and the agent image; see
+[Linux](#linux).
+
+#### Windows
+
+You need Swift 6.2 or later for Windows ([swift.org/install/windows](https://www.swift.org/install/windows/)),
+which brings the Visual Studio build tools it needs, and Docker Desktop
+(WSL 2 backend, Linux containers) or Podman Desktop with a Podman machine.
+In a Developer PowerShell:
+
+```powershell
+git clone https://github.com/Kernel-Hunter/mudroom
+cd mudroom
+swift build -c release -Xcxx -D_ALLOW_COMPILER_AND_STL_VERSION_MISMATCH
+copy .build\release\mudroom.exe $env:LOCALAPPDATA\Microsoft\WindowsApps\ # or anywhere on your PATH
+mudroom image build --backend docker
+```
+
+The `-Xcxx` flag is only needed when your Visual Studio is newer than the
+Clang in your Swift toolchain (Visual Studio 2026 with Swift 6.2): the C++
+headers then refuse to build swift-crypto's BoringSSL. Run `mudroom` from
+Windows Terminal or any console with VT support (Windows 10 1809 or later).
+See [Windows](#windows-1) for what is different there.
+
## Setup
The Setup window opens on the first launch. It has four steps:
@@ -477,11 +527,27 @@ claude`.
**Discard** (⌘⌫). Each apply can be undone in one step. Space toggles the
selected file.
-| | |
-|---|---|
-|  |  |
-|  |  |
-|  |  |
+The Network tab, the timeline and conflicts are shown under
+[Features](#features).
+
+
+More screenshots
+
+
+
+Dark mode, split diff:
+
+
+
+After a partial apply:
+
+
+
+New session:
+
+
+
+
Agents are interactive terminal programs, and you often need to answer them,
so sessions run in Terminal.app instead of a terminal built into Mudroom. The
@@ -1573,12 +1639,3 @@ MIT. See [LICENSE](LICENSE).
Built by [Karim Masmoudi](https://github.com/Kernel-Hunter). My other projects are at [karimmasmoudi.vercel.app](https://karimmasmoudi.vercel.app/projects/).
-## Star history
-
-
-
-
-
-
-
-
diff --git a/docs/assets/mudroom-banner-dark.png b/docs/assets/mudroom-banner-dark.png
new file mode 100644
index 0000000000000000000000000000000000000000..db6fb5e30a9f05d8b8b9031be4386c61c9664a4d
GIT binary patch
literal 220095
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