Documentation

AI coding agents are at their best with full permissions. They install, build, test and iterate without stopping to ask. That is exactly what --dangerously-skip-permissions unlocks in Claude Code. On your actual machine it is a disaster waiting to happen: one wrong command can overwrite system files, read your credentials, or reach into every other project you have. Cleat gives the agent that same unrestricted flag, safely, inside a container that cannot touch your host.

Why not just write a Dockerfile?

You could. But then you handle UID/GID mapping, clipboard bridging, auth sharing, session persistence, per-project container naming and a dozen edge cases. Cleat does all of it in one command and keeps your files owned by you, not root.

Requirements

• Docker. Cleat starts it for you when it's down and offers to install it when it's missing. Prefer to set it up yourself? Get Docker, then confirm with docker run hello-world.
• macOS or Linux (Windows via WSL2). On macOS, Docker Desktop is the easy way to get Docker. Cleat also runs on plain Docker Engine, so it doesn't require Desktop.
• An Anthropic account (Pro, Max, Team, or Enterprise) or an API key. Already signed into Claude Code on this machine? Cleat reuses that login automatically.
• git, used by the installer and by cleat update.

This clones Cleat to ~/.cleat, checks out the latest stable tag and symlinks cleat onto your PATH.

Prefer to read it first? curl -fsSL https://cleat.sh/install -o install.sh, inspect it, then run bash install.sh, or clone the repo and run ./install.sh yourself. If you cloned or moved the script, cleat install symlinks it onto your PATH and cleat uninstall removes it. Then drop into any project and go:

The first run downloads a prebuilt image once (later runs reuse it instantly), starts the container, shares your Claude auth and launches Claude, locked down by default:

No git identity, no SSH keys, no env files, no Docker socket: just your repo at /workspace and Claude's auth. You add access deliberately with cleat config (next sections).

That → /workspace is the locked-down default. Grant the docker cap and the Project line instead reads (same path, sandboxed). Your repo mounts at its real host path so in-container docker commands resolve on the host daemon. That's the only thing that moves it. See what a configured start shows.

Signing in

If you already use Claude Code on this machine, you're set. Cleat mounts your existing ~/.claude login, so nothing else is needed. If Claude asks you to log in, run cleat login once the container is up: the OAuth page opens in your browser and the callback is proxied straight back into the container. You only log in once and it's shared across every project and box.

If the first run fails

• Docker isn't running: Cleat starts it for you (Docker Desktop, OrbStack, or Colima on macOS. Desktop or a rootless engine on Linux. The Windows-side Desktop from WSL2), waits, then continues your command. No docker CLI at all? Cleat offers to install one. Where it can't start Docker (root-owned engine, script, CLEAT_NO_AUTOSTART=1), it prints the exact command to run instead.
• "permission denied … /var/run/docker.sock" (Linux): your user isn't in the docker group. Run sudo usermod -aG docker $USER, then log out and back in.
• Claude asks you to log in: run cleat login (see above).

The daily loop is six commands. They all act on the current directory.

Sessions live on your host, not in the container, so cleat rm never loses your work. cleat resume recreates a fresh container and picks up exactly where you left off. Once a container is running, cleat login signs you in: the OAuth page opens in your browser and the callback is proxied straight back into the container.

By default the sandbox is sealed. Capabilities are opt-in grants that extend what it can reach on your host. Each one is off until you turn it on. Manage them with cleat config:

mount capabilities give the container something from your host (files for git, ssh, gh and hooks, plus environment variables for env), while sandbox capabilities change the isolation boundary itself. There is exactly one of the latter, docker. Cleat warns loudly on every start.

What a configured start shows

Turn caps on and the summary lists exactly what's mounted, grouped by category. The docker cap also mounts your workspace at its real host path, so the Project line reads (same path, sandboxed) instead of → /workspace. A loud warning also prints on every start:

You can skip this until you need it. A single default sandbox is all most people ever use. Boxes are here for when one project needs more than one posture at once.

A box is a named sandbox for the current project. Every box mounts the same live /workspace (the same uncommitted files), but each gets its own capabilities, trust, writable layer and Claude session. The grammar is cleat <verb> [box]. The token after the verb is always a box name, never a path.

This buys you least privilege within a single repo. Run a locked-down editing box beside a cloud-capable one over the same code. The editing box genuinely cannot reach what the other holds:

A named box reads .cleat.<box> if present, otherwise it falls back to .cleat. This is replace, not merge: a box can declare fewer capabilities than the project default, which is the whole point. Trust, env files (.cleat.<box>.env) and Claude sessions are per-box too: approving the az box never grants dev those caps, while cleat resume dev never crosses into az's conversation.

A kit is a curated Claude Code pre-configuration (a CLAUDE.md policy plus custom subagents) enabled for one box with one command: the setup power users hand-build and the first feature that makes a Cleat box a better place to run Claude, not just a safer one. The flagship, plan-big-execute-small, adapts the coordinator pattern from Anthropic's cookbook (big models for planning, small models for execution): your session's model (pick Fable 5 once with /model) plans and reviews every result while worker and scout subagents (Sonnet 5 by default) carry the mechanical bulk at the worker model's rate, each in its own context window, so the session stays lean and heavy work burns your rate limit far slower. It merges over your own config, never touches your host and cleat kit show prints every line before you enable it. To verify it is routing, check /usage after a heavy session: the bulk of tokens should sit on the worker model.

A kit merges on top of your own setup inside the box. Your global CLAUDE.md content comes first, byte for byte, then a short marked Cleat box notes section every box carries (the clipboard-bridge rules: copying to your host clipboard works, paste-back does not), with the kit's section clearly marked below it. Your own agents sit beside the kit's (a same-named agent of yours wins). Your commands, skills and settings pass through untouched. And it is per box: main can stay vanilla while a refactor box runs the planner kit on the same repo.

Your host is never written. The kit exists only as read-only files masked over ~/.claude/CLAUDE.md, ~/.claude/agents and ~/.claude/commands inside the container. Native claude on your machine never sees it and the caged agent cannot rewrite its own instructions. Kits contain instructions and subagents only. No hooks, no settings, nothing that executes as a program and cleat kit show prints every line before you enable one.

The boundary is the container itself. The agent writes only /workspace and the container's throwaway layer. Everything else on your machine is out of reach unless you grant it.

Workspace trust

A .cleat file lives in the repo, so it is untrusted input. Cleat never applies its capabilities silently. The first time a project requests them, you get a prompt that defaults to no. In non-interactive contexts (CI), project caps are dropped unless you opt in. Your global config and --cap flags are always trusted, because you wrote them.

Resource limits & honesty

Each box runs with --init (a real PID 1 that reaps orphaned processes, so long sessions can't wedge on zombie buildup and cleat stop is instant), a memory ceiling sized to your Docker VM (a quarter of VM memory, clamped to 4–8 GB, with swap off so a runaway process OOMs inside its own box instead of freezing every session) and --pids-limit 4096 (a fork-bomb guard) on Docker's default bridge network. Your host is reachable at host.docker.internal. Files the agent creates are owned by you, via UID/GID remapping. Need more headroom for a heavy build, or want a box pinned to fewer cores? Set it per project or per box. Repo-supplied values are capped (8g memory, your machine's core count for cpus) so an untrusted .cleat can't overcommit your machine:

If a session is ever killed by that memory ceiling, Cleat says so (and what to do) instead of leaving an unexplained crash. The usual culprit is a test runner: jest and vitest start one worker per CPU and a box sees every host core, so a small box can spawn a dozen Node workers and blow its ceiling. Cap the workers (jest --maxWorkers=2), give the box more memory, or set cpus so the runner self-limits.

Prebuilt images are multi-arch (Intel and Apple Silicon both run natively, never under emulation). cleat prune clears cleat's own stale images (superseded builds and pulls, never your boxes or other projects). Cleat watches for this itself: when stale images pile up it offers the prune on start. Closing a terminal ends the session but leaves the box running, still reserving its memory ceiling, so on every start Cleat first stops other idle boxes that are safe to stop (detached, no agent running, idle past a grace window) and tells you what it freed. A box working unattended (terminal left open) is never touched. If running sessions still reserve more memory than the Docker VM has, Cleat names how many are running and your real RAM and the VM, before the freeze does. A box and a worktree are the same thing (one session, one memory ceiling), so Cleat sizes the VM with comfortable headroom for parallel work (a ≈16 GB default, capped at half your RAM) and, when yours is smaller, tells you the exact value to set, the click-path and your machine's safe max, naming the Docker Desktop knobs the CLI can't touch (memory, swap, VirtioFS) and keeps reminding you until you fix it. That's a default, not a cap on sessions: a ceiling is a limit, not a reservation, so you can run many sessions at once and the VM only swaps if a lot of them go genuinely heavy on memory at the same time (rare and no different from Claude Code outside Docker). When the VM is already as large as your RAM can safely back, it says so and steers you to running fewer sessions instead of asking for memory that isn't there. It checks swap too: memory and swap are separate Docker Desktop sliders, so if you bump memory (often on Cleat's advice) but leave swap at the default, Cleat flags just the swap, so a brief spike pages out instead of freezing a session. And when your VM is sized right, Cleat says so on every start with a one-line nod (✔ Docker tuned for Cleat) right above Image ready, so a good config gets confirmed, not just a bad one flagged. The wording is engine-aware: on a native Linux engine there is no VM and no slider, so the nod reads ✔ Docker ready for Cleat (16 GB RAM, ...) instead. A small host (under 8 GB) states its size without the parallel-headroom claim.

To be candid: these are plain Docker containers, sharing your host kernel, not microVMs with a separate kernel. Cleat trades that stronger boundary for a true one-command experience, session persistence and the clipboard bridge. For most local agent work, that is the right trade. For genuinely hostile code, a separate VM is the stronger boundary.

Copy-paste starting points for the things people actually do.

• Docker down? Cleat starts it. Missing? Cleat offers to install it. A session verb that finds the daemon unreachable launches your own Docker (Docker Desktop, OrbStack, or Colima on macOS, Docker Desktop or a rootless engine on Linux, the Windows-side Desktop from WSL2), waits with a bounded spinner, then continues your command. A root-owned Linux engine gives you the exact one-line command instead. A remote tcp:// endpoint is named so you start it where it runs. No docker CLI at all? An interactive, consent-first install offer (macOS picks Desktop / OrbStack / Colima via Homebrew's official packages, Linux runs Docker's official script under sudo only after you say yes, WSL2 uses winget), with the exact command always shown and No as the default. Interactive terminals only, so scripts and CI never pop a GUI or an installer. CLEAT_NO_AUTOSTART=1 turns all of it off.
• Root-only hosts work. On a stock VPS image (or under sudo) the box user maps to uid 0. Claude Code itself refuses --dangerously-skip-permissions as root, which used to end every session with "Claude exited with code 1". Cleat now sets IS_SANDBOX=1 (Claude Code's own escape hatch for sandboxed containers) on each session for root hosts only, so sessions launch normally and existing boxes heal on their next attach.
• Enabling a cap recreates the container. Mounts are fixed at create time, so the next cleat after a config change prompts to recreate. Sessions survive via --continue.
• Only a real config change prompts a recreate. Resizing your Docker VM or upgrading the CLI never does. The recreate prompt fires only when a capability, an environment key, or a configured [resources] limit actually differs from how the box was created, never because a value Cleat derives from the VM moved underneath you.
• A box from before the read-only ~/.claude masks says so. Bind mounts are baked at create, so an older box keeps those surfaces writable until recreated. Every start notes it until you run cleat rm && cleat.
• The VM size Cleat shows matches your slider. docker info reports the guest kernel's memory, which sits under the Docker Desktop slider by a reserve that grows with VM size (a 24 GB VM reads ~23.4 GiB), so Cleat reads the slider value straight from the Docker Desktop settings (the same way it reads swap), falling back to rounding the kernel's memory when that can't be read. The display and the undersized check share that one value everywhere (the advisory, the tuned nod, cleat status), so a correctly sized VM is never falsely flagged as too small and the number you see is the slider you set.
• Ad-hoc installs survive stop and reboot. Per-container state lives under ~/.config/cleat/run, not /tmp, so macOS file rotation can't trigger a surprise recreate that wipes what you installed inside the box.
• An ssh box survives a reboot. macOS regenerates your SSH agent socket path on every restart, so the path baked into the box goes stale. Cleat spots the vanished mount before starting and recreates the box transparently. No cryptic mount … not a directory error, no lost session.
• Trust and MCP approvals are per-project. Each project keeps its own isolated .claude.json, which fixed the old corruption crash, but approvals no longer carry across repos. Approve once per project. Your login is unaffected.
• Use host.docker.internal, not localhost, to reach a service on your host (an MCP server, a local proxy). Inside the container, localhost is the container. On Linux, Cleat wires up host.docker.internal for you automatically.
• With the docker cap on long sessions, a Docker Desktop restart can renumber the socket group. Cleat re-heals access on every attach. If the socket itself was replaced, it tells you to run cleat stop && cleat resume rather than killing your live session.
• Prompts treat redirected stdin as a decline. Every [Y/n] read from /dev/null or a wrapper means no, never a silent yes. Update checks are throttled and never downgrade.
• Cloud CLI caps were removed. az, aws and gcloud are gone. Install the CLI on your host and pass credentials through the env cap instead. Old aliases like --cap aws now fail with "Unknown capability" rather than silently doing nothing.

Commands

Flags

Configuration files

Environment variables

All ~/.config/cleat paths honor $XDG_CONFIG_HOME if it is set.

Full release history is on the changelog. The source lives on GitHub.