zeroclaw is one config file and one binary wrapped around your model provider

The recommended install pipes a script from master straight into sh

The install path a Unix user is pointed at fetches a shell script from the default branch and hands it to sh, then invokes the binary from a Cargo style bin directory:

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh
"${CARGO_HOME:-$HOME/.cargo}/bin/zeroclaw" quickstart

The default branch is master and the URL names that branch, not a tag, so what you execute is the tip of the branch rather than the v0.8.7 release published on 2026-10-27. The second line also assumes the binary landed in the default Cargo location, so a custom CARGO_HOME changes the path you have to invoke. The README block containing these commands is marked as generated by a cargo command and not to be edited, and the complete flag reference lives behind `./install.sh --help`. Windows is handled differently: the guide there points at a prebuilt PowerShell path that needs no Rust toolchain, installs the current release, updates PATH, and runs Quickstart.

YOLO mode sits one link away from the approval gates

Autonomy is a setting, and the default is called supervised: medium risk operations require approval and high risk ones are blocked. Around that sit workspace boundaries, a command policy, OS level sandboxes through Landlock, Bubblewrap, Seatbelt or Docker, and cryptographic tool receipts written on every action. The same document then offers a YOLO mode for trusted development boxes that skips the safety gates. The consequence is that the guardrails are a configuration decision rather than a property of the binary, and the binary will run shell, browser, HTTP, hardware and custom MCP server tools when told to.

Every key has an environment mirror and the old fallbacks were deleted

As of v0.8.0 there is a single environment override grammar, `ZEROCLAW_<dotted_path_with_double_underscores>=<value>`, where each doubled separator is one step of the path and the tail repeats the TOML path in order. The provider specific fallbacks and the earlier generic ones, including `API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `PROVIDER` and `ZEROCLAW_MODEL`, were removed outright. The example file keeps its entries commented out, with an alias that contains one, a model, and a key:

# ZEROCLAW_providers__models__openrouter__prod_v2__model=anthropic/claude-sonnet-4-6
# ZEROCLAW_providers__models__openrouter__prod_v2__api_key=sk-or-...

So a deployment carrying an old environment file no longer gets its credentials from those variables. The separator rule is also worth reading twice: one underscore inside a field name joins snake case into the schema's kebab case form, while underscores inside an alias are literal characters, which is why `api_key` and the alias `prod_v2` appear in the same block. The compose file wires the same grammar as a live variable, `ZEROCLAW_providers__models__openrouter__default__api_key=${OPENROUTER_API_KEY:-}`, and runtime knobs follow the same path, with `ZEROCLAW_gateway__request_timeout_secs=120` and its long running counterpart at 900.

A working V3 config is four section headers, not one key

Configuration lives in one TOML file at `~/.zeroclaw/config.toml`, and the project says a V3 config has at least four section headers, each shaped as type and alias: a provider entry, an agent that references it, and a risk profile that agent gates against. The first four commands are what turn that structure into a running loop:

zeroclaw quickstart               # one-shot setup: pick a provider, write a working config
zeroclaw agent -a <alias>         # interactive chat using the [agents.<alias>] entry
zeroclaw service install          # register as systemd/launchctl/Windows Service
zeroclaw service start            # run it always-on in the background

Because the agent references the provider by alias, the name is a live link rather than decoration, so renaming a provider alias means editing the agent that points at it. The service pair is also the difference between a tool you run and a resident process that answers on its own.

Codex auth is a stored profile, not an api_key on the entry

Subscription style authentication takes a different shape from a plain key, and Quickstart will write the provider entry for you:

zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json  # if already signed in with Codex CLI
zeroclaw quickstart --model-provider openai-codex --model gpt-5.4

The entry it produces looks like this, with type and alias you choose yourself:

[providers.models.openai.coding]   # type = openai; alias = coding (you choose)
model = "gpt-5.4"
wire_api = "responses"
requires_openai_auth = true

The notes are explicit that normal Codex auth uses stored auth profiles and not an api_key on the provider entry, while Claude Max setup token auth stays on the Anthropic slot: you run `claude setup-token`, pick `setup_token` in Quickstart, and paste the result into the prompt. Two providers, two auth shapes, and an agent entry pointing at the alias with `model_provider = "openai.<alias>"`.

The distroless image exits immediately on ARM64

The published compose file runs `ghcr.io/zeroclaw-labs/zeroclaw:latest`, and its own comments say that on ARM64 environments the distroless image exits immediately, with the Debian compatibility image given as the switch. The trade off is the one the file states: the distroless variant has no shell at all, while the Debian variant includes bash, git and curl. Building locally is offered both ways, once from the distroless Dockerfile and once from `Dockerfile.debian`. Two more details catch people out. The gateway listens on port 42617, and the comment explains that Docker bridge traffic never reaches container loopback, so a config that persisted `host = "127.0.0.1"` stays unreachable unless the process listens on the container interface. A bind address that works on the host is therefore a real failure mode in the container.

Base images are pinned by digest and the dashboard builds off platform

The Dockerfile does not name base images directly. Each one arrives as a build argument with a digest already baked in, generated from a manifest in the dev and CI directory by a cargo command, so the defaults are node:24-bookworm-slim, rust:1.98-slim, debian:trixie-slim and a distroless cc image on the nonroot user. The frontend stage is pinned to the build platform rather than the target, with a comment explaining that the dashboard bundle is architecture independent, which keeps node and the web build running natively instead of under emulation on a multi platform build.

One shipped binary, thirty workspace members, and two licences

The overview calls ZeroClaw a single Rust binary, and that describes the artefact you install rather than the tree you clone. The workspace lists 42 members, about 28 of them excluding test fixtures, among them crates for providers, memory, channels, tools, plugins, the SOP graph, the gateway, hardware, TLS and the runtime, plus three applications named zerorelay, zerocode and a Tauri app. Alongside them sit fuzz, benches, evals, firmware, deploy-k8s, dist and dev directories, so the release pipeline and its checks are part of the repository. Licensing is worth reading twice as well: the repository is recorded as Apache-2.0, while the workspace manifest declares `MIT OR Apache-2.0` and the root carries both a LICENSE-APACHE and a LICENSE-MIT file. If you intend to vendor or redistribute any of it, that is the line to check rather than the badge.

Editorial conclusion

Adopt it if you want a self hosted agent loop you can pin, audit and switch providers on, and read the autonomy and sandbox settings before the first run rather than after it. Do not adopt it expecting a finished assistant, because the safety tiers, the channel set and the container images are all yours to configure, and a single binary is what ships, not what you get to skip.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes