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 install script and by cleat update on a script install. A Homebrew keg needs neither.

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

Or with Homebrew:

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. Two things move it: that cap plus --fork, which points /workspace at the box's own copy and adds a Fork: line to the summary. 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:

The editor's global scope has one more row: generate a project .cleat. It stamps your current caps and resource limits into ./.cleat so a per-project cage is one keystroke, not an INI you write from memory. It preserves an existing [setup] section and does not auto-trust: the generated file goes through the normal trust prompt on the next run, exactly like a repo-shipped one.

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. By default every box mounts the same live /workspace (the same uncommitted files), but each gets its own capabilities, trust, writable layer and Claude session. A fork box is the exception: it mounts its own copy instead. 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:

What a box may reach is declared in one place, the project's .cleat, as a section named after the box (below). A box can hold 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.

Per-box configuration#

One project, one config file. A box scopes any section by name, so the posture of every box in the repo reads top to bottom in a single diff:

The syntax is [box.<name>.<kind>], where <kind> is caps, resources, setup or fork. A declared section replaces the bare one. An absent section inherits it. Declared but empty is a real value rather than absence, which is what preserves least privilege: [box.locked.caps] with nothing under it means zero caps, not "inherit everything". caps, setup and fork are lists that replace wholesale. resources is key by key, so declaring memory for a box leaves its cpus inherited. [box.main.<kind>] is honoured like any other box, never special-cased.

Two things stay outside those sections. Env vars keep their own sidecar file (.cleat.<box>.env, falling back to .cleat.env), so an az box's credentials are never visible to a dev box. And per-box sections are project-only: box names mean nothing outside a project, so a [box.*] section in your global config is ignored with a warning. Resource values from a repo file are still clamped (8 GB memory, your machine's core count for cpus), per-box sections included, so a .cleat asking for 16g still runs at 8g.

Trust follows the section. The capability hash is per box, so editing one box re-prompts that box alone and the prompt names the subject it is approving. cleat config <box> edits those sections for you. Enabling a cap on a box that is still inheriting writes the inherited set out first, so cleat config review --enable gh against a project [caps] of git ssh leaves that box on git ssh gh. Edit a box back to exactly what it would inherit and the section is removed, so it inherits again. Empty it and the bare header stays, because dropping it would hand a locked-down box the project's full set the next time the project gains a cap. cleat config <box> --list marks every value declared or inherited and names the box it is showing.

A box normally shares your live project directory. --fork gives it its own copy, so an agent can work without touching your tree.

Run it a few times and you have several agents on one project, each in its own container working on its own files. They still share what every box shares: your Claude login and the host ~/.claude/plugins.

It is a copy rather than a git clone, so submodules, untracked sibling repos, uncommitted work and node_modules all come along. A project with no git at all works the same way. Symlinks are copied as symlinks and never followed, so a project holding sub/keys -> ~/.ssh does not put real key bytes in the cage. On macOS the copy is copy-on-write, so it is close to instant and costs almost no disk until something changes.

The launch summary names the copy and how old it is, so a stale fork is never silent:

A box's workspace is fixed when the container is created, so the flag only does something at create time. Passing --fork to a box that already exists as a plain box is refused rather than quietly ignored, with cleat rm as the remedy. Forking a fork, or putting the fork root inside the project so the copy would contain itself, is refused too. cleat rm frees the container and keeps the copy, because it may hold the only version of the work. Because it is kept, starting the box again with --fork reuses that copy rather than taking a fresh one, so a change to [fork] exclude does not apply until you refresh it.

The copies outlive their boxes on purpose, so they get their own verb. Note that fork is a verb here while --fork stays a flag on start and run. cleat fork start feat-a and cleat start feat-a --fork are the same command, because fork is the noun people reach for. Both start and run are offered because the difference matters: run creates the box then returns you to your shell while start creates it and launches Claude in it.

cleat fork path feat-a prints one copy's path and nothing else, so cd "$(cleat fork path feat-a)" works. cleat fork rm deletes one copy. cleat fork prune deletes copies whose container is gone, plus any stale fork marker. cleat fork refresh replaces a copy with a fresh one from the live project. Size is apparent, not reclaimable: du is not copy-on-write aware, so a fresh copy reports its full size while sharing nearly every block with the project. rm and refresh refuse while the box exists, because its container has the copy mounted at /workspace. Both confirm, defaulting to no. Both say plainly that uncommitted agent work in the copy will be lost.

Exclude what you do not want with [fork] exclude = node_modules in .cleat. An exclude that is an absolute path, contains .., names the workspace root, or resolves outside the copy through a symlink is refused with a warning instead of being deleted. [fork] dir moves the fork root if your projects live on another volume, since copy-on-write only works within one. It is read from your global config only and must be an absolute path: a project .cleat cannot move it, because that file arrives with a cloned repo and the value is a path Cleat creates and deletes under.

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, reading it back from the shell 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 still read exactly as they do on your host, through a read-only copy. 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, ~/.claude/commands, ~/.claude/skills and ~/.claude/plugins inside the container. Native claude on your machine never sees it and the caged agent cannot rewrite its own instructions. Other projects are invisible too: a box gets a generated ~/.claude/projects holding only its own sessions, so it cannot read another repo's transcripts, while its own session stays writable so --continue keeps working. A read-only mask would not be enough there: measured, :ro blocks writes while leaving a sibling project's transcript perfectly readable, so these are generated replacements and the host content is simply never mounted. The same treatment covers file-history, paste-cache, uploads, backups, shell-snapshots, sessions, tasks, jobs and hooks. hooks is the sharpest of them, because the hooks capability runs your hook commands on the host and the usual way to write one names a script under ~/.claude/hooks/, so a box able to write there could rewrite what your host runs. What a box can still reach is the project you mounted plus your Claude login, which it needs in order to authenticate. 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.

Copy a screenshot on your host, click into a box's Claude prompt and press ctrl+v. About a second later the prompt shows [Image #1], exactly as it would outside Docker. Pasting a picture into a caged agent just works.

It is ctrl+v, not cmd+v. That is fixed. Claude Code inside the box reports platform linux, so it binds image paste to ctrl+v. On a Mac, cmd+v is the terminal's own text paste and never reaches the image handler. The feature is on by default. It needs no config and no recreate: every existing box picks it up on its next session.

Every box starts from the same base image. Anything the agent installs by hand survives stop and start, then disappears the first time the box is recreated. A [setup] section in your project's .cleat is the durable form: real shell commands that Cleat runs once inside a fresh box, before the session starts, so a recreated box comes back with your toolchain already on it.

A line is either a shell command, run verbatim, or script <path>, which inlines a project-relative file at that position. Mix them freely, in any order: they become one payload that runs top to bottom. A script target has to be a real file inside the project, so absolute paths, .. segments, symlinks and anything resolving outside the project root are all refused before a single command runs. Keeping the steps in a file means your teammates and CI run the identical bytes you approved.

What actually runs#

The payload is staged into the box and executed as coder (passwordless sudo, full network access) with /workspace as the working directory, under bash -e, with stdin closed. Three consequences worth planning for. The first failing command stops the rest. Nothing can sit waiting for input. An export reaches later lines of the same payload but nothing afterwards. Output streams live, so you watch it install.

Approving it#

A .cleat lives in the repo, so it is untrusted input. Running arbitrary shell as a sudo-capable user is a materially bigger grant than mounting a file. [setup] gets its own consent class because of that. Trusting a project's capabilities never trusts its [setup]. The reverse holds too. CLEAT_TRUST_PROJECT deliberately does not cover it: only CLEAT_TRUST_SETUP or --trust-setup does.

The first time a project declares [setup], or after any edit to it, you get a default-no prompt showing the exact payload before anything runs. Approval is byte-exact and covers every inlined script file's contents, so a single changed byte re-prompts. Cleat rebuilds and re-hashes the payload immediately before executing it, which means an agent that rewrites /workspace/.cleat mid-session cannot ride your earlier approval. Declining never blocks the box: it starts without provisioning and tells you how to approve later.

If the commands themselves fail, the box still opens. You get an amber warning naming the exit code, nothing is marked applied and the next start tries again from the top, so write the steps to be safe to re-run.

[setup] is project-only and box-aware: a [box.<name>.setup] section replaces the plain [setup] for that box rather than merging with it, with trust recorded per box. Starters for .NET, Python and Rust live in examples/, one showing inline commands, one a single script file and one two scripts plus a trailing inline command.

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.

Trust is per (project, box). A named box hashes the capabilities it actually resolves to, its own [box.<name>.caps] when it declares one, so editing one box re-prompts only that box and cleat trust <box> approves exactly that box, recording the same row its start-time prompt would. The prompt names what it is approving, down to .cleat [box.web.caps], because with one file per project the box name is the only thing telling two consent decisions apart. A lone box name is always that box. A token containing a slash is a path and selects the main box, so cleat trust and cleat untrust stay symmetric.

Setup: a second consent class#

A project's .cleat can also declare a [setup] section: real shell commands that run in the box as coder before the session starts. That is a materially bigger grant than a mount, so it is approved separately, byte-exactly, with a default-no prompt that shows the payload first. Trusting a project's caps never trusts its [setup]. CLEAT_TRUST_PROJECT deliberately does not cover it either. The full story is in Provisioning.

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 in the cleat config editor (the Resources group, arrow keys to cycle) or with a flag, no INI required:

The editor's choices come from your actual machine. The cpus ring is built from the core count Docker reports, so it never offers more cores than you have and never stops at 8 on a 24-core box. The memory ring climbs in real stops to the size of your Docker VM, so a 24 GB VM offers the full 24 GB. Someone who runs one box at a time is entitled to it.

Nothing above 8 GB is blocked, only annotated. The note gets blunter as the number climbs: first a reminder that a ceiling is not a reservation, then a warning once you pass half the VM, then an amber warning at the whole VM with the full reason on save. A box that really grows into the entire VM leaves nothing for the daemon or the VM's own kernel, so the Linux OOM killer inside the VM starts firing. That can take out a working agent mid-write or wedge Docker until you restart it. You are told, then you choose.

Both write the same [resources] section, so hand-editing stays a valid fallback and the reference format. Repo-supplied values are capped (8g memory, your machine's core count for cpus) so an untrusted .cleat can't overcommit your machine. The project ring stops at 8g for the same reason, rather than offer a ceiling the box would silently not get:

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. And because a warning that scrolls past protects no one, an undersized VM (or default swap) actually holds the launch: Cleat stops on a prominent banner, shows the fix and waits for you to press Enter, so you can't miss it. That hold is one of two places Cleat blocks the start (a nearly-full Docker disk is the other, below). It fires only on a real interactive terminal, so cron, pipes and CI sail straight through. CLEAT_NO_DOCKER_GATE=1 skips it for a machine that can't spare the RAM. 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.

Disk is the other pressure Cleat watches. On Docker Desktop every box shares one VM disk, so a box that reads 100% full is really the whole store filling up, not that one box. cleat storage shows the breakdown: your images and boxes, the shared build cache, plus everything else labeled other projects, with a fill bar and the reclaim levers. When the store crosses about 85% full with little free space, Cleat drops a one-line advisory. When it crosses 95% with under 10 GB free, it holds the launch the same way the memory gate does (CLEAT_NO_DISK_GATE=1 skips it). Each check pairs the fill percentage with a free-space floor, so a small disk trips when it is genuinely tight while a 1.8 TB store at 95% with 90 GB still free never does. cleat prune --cache is the safe lever for the build cache. The fix guidance is written for your engine: the Docker Desktop slider, OrbStack auto-reclaim, Colima resize, a native-Linux prune or a WSL compaction.

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.

• The docker cap binds the socket where your engine actually runs. Since v1.4.3 the bind is engine-aware. A VM-backed engine (Docker Desktop, OrbStack, Colima, Rancher Desktop, Lima) gets the in-VM /var/run/docker.sock. A host-local daemon gets its real socket, rootless included. A loopback tcp:// DOCKER_HOST counts as local. A socket that is not there is never bound, so a stopped daemon can no longer leave a phantom directory on the host. Remote daemons over tcp:// or ssh:// are not a supported target: a box mounts your project by host path. A TLS remote gets a plain warning that the client certificates stay on the host.
• Per-box .cleat.<box> files are no longer read. Per-box config moved into the project's own .cleat as [box.<name>.<kind>] sections, so a week of boxes stops leaving a pile of committed dotfiles in your repo root. A leftover file changes nothing silently: it warns whenever that box starts, naming the sections to move it to. Delete it once you have. Env is the exception that stays a file, as .cleat.<box>.env.
• A box never replays an old copy onto your clipboard. A copy made inside a box lands on your host clipboard while a session is attached, exactly then. Anything left over from an earlier session is discarded at the next start instead of overwriting what you currently have (before v1.2.5 it could).
• 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 ad-hoc install still dies on recreate. sudo apt-get install survives stop and start just fine, but config drift, an image refresh or a stale-mount auto-recreate all start the box from the base image, wiping it. A [setup] section is the durable path: approve it once and it re-runs automatically after every recreate.
• 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.
• Switching install method loses nothing. Config, trust, boxes, fork workspaces and Claude history all live outside the install itself (~/.config/cleat, ~/.claude, your project's own .cleat). Container names are derived from the project path rather than from where Cleat is installed. A box you made under one install is the same box under the other. Remove the one you have, add the other, carry on.
• One cleat per machine. Cleat's own installers, the curl script and cleat install, refuse to create a second one. Homebrew installs its keg without that check, so a brew install can sit next to a script install, which cleat status flags when it finds more than one. Two cleats means a bare cleat resolves to whichever comes first on your PATH. The loser stays invisible until it bites: a stale version that "fixes itself" after a shell restart, an update that appears to do nothing. Re-installing over the path you already have is fine, that is just an upgrade. A different path is refused, though --force replaces it. A Homebrew keg is never replaced even with --force, because that would leave brew tracking an install it no longer owns. The scan looks at every PATH entry plus the usual install directories even when they are off PATH, since a Homebrew prefix is invisible to a shell that never ran brew shellenv. cleat status names them all when it finds more than one. Every interactive start also warns about the split, silenced with CLEAT_NO_INSTALL_CHECK=1.
• A Homebrew install is brew's to manage. If cleat is running from a Homebrew keg, cleat update runs brew upgrade cleatdev/tap/cleat for you and cleat uninstall offers brew uninstall, asking first because that removes the whole keg where the command normally just drops a symlink. cleat install refuses outright, since brew already linked it. The on-start upgrade offer works the same as on a script install: same throttle, same "don't ask me again", same session continuing afterwards, just applied with brew upgrade instead of a checkout. Otherwise cleat update would fall through to "re-install with curl", which symlinks over /usr/local/bin/cleat. That path is Homebrew's own bin on an Intel Mac, so you would end up on a forked copy while brew still tracked an orphaned keg. Cleat decides by where the resolved binary physically lives, never by the directory you invoked it through. Detection never shells out to brew, so it still holds where brew is off your PATH. There the command is printed for you to run.
• 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.