Mudroom
Security Notice
This extension includes AI agent skills that can modify AI assistant behavior. Review the skill files before installing.
Run Claude Code (and other workloads) inside a macOS apple/container sandbox.
Creates one container per workspace — defaulting to the Microsoft typescript-node devcontainer image (Debian 12 bookworm-based, ships node, npm, git, gh, and gnupg) and overridable per sandbox. Bind-mounts the host workspace directory into the guest, and injects the host Claude Code credential so the guest session shares the host subscription without exposing secrets in argv.
The trust boundary is the container itself: the host filesystem outside the bind-mounted workspace is not exposed, but inside the guest Claude has Bash(*) and full network egress. Mudroom is container-isolation, not Claude-permission-isolation — anything Claude does inside the box can curl, install packages, and write to the mounted workspace.
Includes the mudroom host-side CLI wrapper and the mudroom-setup skill that installs a shell function pointing at the bundled binary.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| containerName? | string | Name used for the apple/container instance (also used as its ID). |
| workspaceHost | string | Host filesystem path to bind-mount into the sandbox at /workspace. |
| image | string | OCI image used for the sandbox guest. Defaults to the signed |
| swampSourceHost? | string | Host path to bind-mount read-only at /home/node/.swamp/source inside |
| sessionsHost? | string | Host path to bind-mount read-write at /home/node/.claude/projects |
| Argument | Type | Description |
|---|---|---|
| installKernel? | boolean | Pass --enable-kernel-install (default: true). Set false if the |
| Argument | Type | Description |
|---|---|---|
| command | array | Command and arguments (argv-style) |
| workdir? | string | Working directory inside the sandbox (defaults to /workspace) |
| timeoutSeconds? | number | Kill the command after this many seconds (client-side abort) |
| Argument | Type | Description |
|---|---|---|
| workspacePath? | string | Host directory containing `.mudroom.yaml`. Defaults to |
| Argument | Type | Description |
|---|---|---|
| workspacePath? | string | Host directory to write `.mudroom.yaml` into. Defaults to |
| force? | boolean | Overwrite an existing `.mudroom.yaml` (defaults to false). |
| Argument | Type | Description |
|---|---|---|
| workspacePath? | string | Host directory containing `.mudroom.yaml`. Defaults to |
| Argument | Type | Description |
|---|---|---|
| cwd | string | Host workspace directory. Symlinks are resolved before hashing. |
| Argument | Type | Description |
|---|---|---|
| cwd | string | Host workspace directory to scope the listing to. |
| Argument | Type | Description |
|---|---|---|
| cwd | string | Host workspace directory to scope the prune to. |
| dryRun? | boolean | Report what would be deleted without making any changes |
| Argument | Type | Description |
|---|---|---|
| status | enum | |
| fromVersion? | string | |
| toVersion? | string | |
| durationMs | number | |
| error? | string |
| Argument | Type | Description |
|---|---|---|
| workspaceHostPath | string | Absolute host path of the workspace directory. On the guest |
| sessionId | string | Claude Code session ID ($CLAUDE_SESSION_ID from the Stop hook). |
| origin | enum | Which side is staging the transcript. |
| Argument | Type | Description |
|---|---|---|
| workspaceHostPath | string | Absolute host path of the workspace directory. |
| Argument | Type | Description |
|---|---|---|
| workspaceHostPath | string | Absolute host path of the workspace directory. |
| sessionsHostOnHost? | string | Host path where guest session .jsonl files live (typically |
| Argument | Type | Description |
|---|---|---|
| workspacePath | string | Host directory that contains (or will contain) |
| mudroomHome | string | Resolved `$MUDROOM_HOME` path (e.g. `/Users/blake/.mudroom`). |
| Argument | Type | Description |
|---|---|---|
| workspaceHostPath | string | Absolute host path of the workspace directory. |
| windowSecs? | number | How many seconds back to look for activity (default 60). |
Resources
Files
updated binaries
Fix mudroom init: skip writeStarterConfig when .mudroom.yaml already exists so hook reinstall works without -f
updated binaries
Fix session handoff: add missing --origin arg and context-aware SWAMP_REPO_DIR in Stop hook; add host→guest .jsonl bridge in claimStage
updated binaries
Hotfix for 2026.05.18.64: the revert missed three multi-line container-exec arrays in auth.ts (credsScript, settingsScript, teamsScript), so the .64 build still pinned --user node on those three injection paths. Result: Claude credentials, default settings, and Linear-MCP teams patch were silently written to /home/node/.claude/ in containers whose bind mounts targeted /root, never reaching Claude on launch — surfaced as the first-run theme/welcome screen. Lint test strengthened to whole-file scan so future array splits cannot hide the same regression. Yanking .64.
updated binaries
Revert: container exec no longer runs as --user node. The .61/.62/.63 series tried to switch the guest user to node so HOME matched the bind-mount target /home/node/.claude/projects; the cascading work (auth.ts inject paths, /home/node/.claude ownership) made it strictly worse than the simpler alternative. Now the bind-mount targets are /root/.claude/projects and /root/.swamp/source, every guest exec runs as the container default (root), and auth.ts is untouched. Session handoff (mudroom resume-host, mudroom doctor, exit-time hint) is preserved. Sandboxes from .60-.63 should still mudroom destroy && mudroom once after upgrading so the fresh container picks up the new mount target.
updated binaries
Fix for 2026.05.18.62: provisionGuest now chowns /home/node/.claude and /home/node/.config{,/swamp,/gh}/aws back to node:node before any auth injection. apple/container creates the intermediate parents of bind-mounted paths (e.g. /home/node/.claude/projects) as root, which silently broke 'cat > /home/node/.claude/.credentials.json' from a --user node exec — surfaced as 'mudroom: injectClaudeAuth failed'. Non-recursive on .claude so the host-shared /home/node/.claude/projects mount keeps its real ownership. Existing sandboxes can heal in place with: container exec --user 0 chown node:node /home/node/.claude /home/node/.config /home/node/.aws — or just mudroom destroy && mudroom.
updated binaries
Fix follow-up to 2026.05.18.61: credential injection methods (injectSwampAuth, injectGhAuth, injectGitIdentity, injectClaudeAuth, injectLinearMcp, injectAwsAuth) now also exec as --user node so their writes land in /home/node/.claude, /home/node/.config, etc. — where claude (which now runs as node) actually reads from. Without this, mudroom 2026.05.18.61 silently dropped Claude creds, gh auth, git identity, swamp auth, Linear MCP, and AWS creds inside the guest. Existing sandboxes still need a one-time mudroom destroy && mudroom after upgrading.
updated binaries
Fix Aapple/container exec now runs as the node user so Claude session jsonls land in the per-sandbox bind mount instead of /root/.claude/projects. Adds mudroom resume-host (bridges guest sessions for native claude --resume on the host) and mudroom doctor (diagnoses stop-hook, sessionsHost config, sessions dir, and runtime user). Existing sandboxes must be recreated once: mudroom destroy && mudroom.
Modified 1 models. updated binaries
updated binaries
Modified 1 models. updated binaries
Modified 1 models. updated binaries
updated binaries
Modified 1 models. updated binaries
updated binaries
updated binaries
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository0/2missing