Quickstart

Quickstart is the guided setup that takes you from a fresh install to a working agent in one pass. It runs on three surfaces: the CLI, the zerocode terminal interface, and the web gateway. All three drive the same underlying flow, so the config they produce is identical. Use whichever fits where you are.

Install

Unix fast path

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

This route is noninteractive and does not open a picker.

It prefers a matching prebuilt binary and falls back to a source build when needed.

A prebuilt archive may contain zerocode; a noninteractive source fallback installs the default app without opening a picker.

The command uses a fixed feature set.

If a source build is needed, the installer can bootstrap Rust when it is missing.

On Unix, the installer updates the shell profile when allowed; reload the parent shell before relying on the new PATH.

The installer skips setup and prints zeroclaw quickstart as the next step.

Unix guided path

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

This route is guided and may offer supported choices.

On supported targets, it offers prebuilt or source installation.

A prebuilt archive may contain zerocode; a source choice selects it by default and allows app selection.

The source path also lets you select optional Cargo features.

If a source build is needed, the installer can bootstrap Rust when it is missing.

On Unix, the installer updates the shell profile when allowed; reload the parent shell before relying on the new PATH.

For an unconfigured install, it offers zeroclaw quickstart or browser-based Quickstart.

Windows prebuilt path

Use the PowerShell block in the Windows setup guide. Installation and PATH setup are idempotent; Quickstart still runs.

This route is noninteractive and does not open a picker.

This route installs a prebuilt release archive.

The archive may also contain zerocode; availability depends on the release asset.

The command uses a fixed feature set.

This prebuilt route does not require a Rust toolchain.

On Windows, the PowerShell path updates the current process and the persistent user PATH.

The PowerShell block finishes by running zeroclaw quickstart automatically.

Advanced source path

Unix

./install.sh --source

This route is guided and may offer supported choices.

This route always builds from source.

Source installation selects zerocode by default and lets you change the app selection.

The source path also lets you select optional Cargo features.

If a source build is needed, the installer can bootstrap Rust when it is missing.

On Unix, the installer updates the shell profile when allowed; reload the parent shell before relying on the new PATH.

For an unconfigured install, it offers zeroclaw quickstart or browser-based Quickstart.

Windows

cargo install --locked --path .

This route is noninteractive and does not open a picker.

This route always builds from source.

This command installs the core zeroclaw binary; it does not install optional apps.

The command uses a fixed feature set.

A Rust toolchain is required before using this command.

This Cargo command does not edit PATH; make sure Cargo’s bin directory is already available in your shell.

After installation, run zeroclaw quickstart.

The steps

Important: if any of these terms are unfamiliar, read Getting Started → Concepts first. It defines model provider, risk profile, alias, and the rest in one place.

Every surface walks the same checklist and writes the same config; only the optional Plugins step is CLI-only for now. Required steps must be satisfied before the agent can be created; optional steps can be skipped.

The runtime profile is set automatically. Quickstart installs the unbounded preset for the new agent. Tune budgets and timeouts afterward by editing [runtime_profiles.<alias>] (see Reference → Config).

CLI

The fastest path on a headless box or over SSH:

zeroclaw quickstart

You answer one prompt per step in the terminal. The built-in cli channel works immediately, so Channels and Peer groups can be skipped. For an all-defaults, no-approvals config, see YOLO mode.

OpenAI Codex subscription auth

Quickstart can configure the OpenAI Codex subscription path without an API key. Authenticate once, then choose OpenAI as the provider and set Authentication to codex when prompted:

# If you already signed in with the Codex CLI:
zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json

# Or start ZeroClaw's own OpenAI Codex login flow:
zeroclaw auth login --model-provider openai-codex

For scripted setup, openai-codex is accepted as a quickstart input alias and writes the canonical [providers.models.openai.<alias>] entry:

zeroclaw quickstart --model-provider openai-codex --model gpt-5.4 --agent assistant

Claude subscription setup-token auth

Quickstart can also configure Claude/Anthropic with a normal Console API key or a token generated by Claude Max:

claude setup-token
zeroclaw quickstart --model-provider anthropic --model claude-sonnet-4-5 --agent assistant

Choose Anthropic, set Authentication to setup_token, then paste the token from claude setup-token into the API key/token prompt. Scripted input may use --model-provider claude as an alias. Quickstart still writes the canonical [providers.models.anthropic.<alias>] entry; the token is stored through the same credential path as api_key.

Plugins

Builds with WASM plugin support add an optional Plugins row to the CLI checklist, after Peer groups. The row exists only when the binary is built with the plugins-wasm feature. Today’s release archives are built without it, so their checklist has no Plugins row; a source build with --preset full and the all-features container image include it. Only the CLI Quickstart offers the row for now: the zerocode and web gateway Quickstart do not list plugins yet. Leaving the row unvisited changes nothing.

Opening the row fetches the plugin registry index, the same one zeroclaw plugin search uses (set ZEROCLAW_PLUGIN_REGISTRY_URL to use another registry), and lists every tool plugin the registry offers or this machine already has, marking the installed ones. If the registry index cannot be fetched, you can retry or continue without plugins. Picking plugins downloads no package and changes no config. Opening the row only writes the registry index cache under the data directory, as zeroclaw plugin search does, and creates the plugins directory if it is missing.

If Quickstart could not read the [plugins] section of the config file, because that section or the whole file is malformed, the row says so instead of fetching the registry. It offers nothing to pick, and Create installs no plugin. Repair the file, then run Quickstart again to install plugins.

If the config file was written by an older ZeroClaw version, Create stops before installing any plugin or creating the agent, and prints the zeroclaw config migrate command that updates the file, as zeroclaw plugin bind does. Run that command, then run Quickstart again. Saving plugin settings into the older file would mark it as current without moving its older settings, which later runs would then stop reading.

When you choose Create, Quickstart installs the picked plugins before it creates the agent. First it checks the rest of your choices, and the configuration they land in, the way the agent step will, including the authorization check the agent step runs before it writes anything. If the agent step would refuse them, for example because a permission profile names an agent that no longer exists, Quickstart reports the problems and stops before any plugin is downloaded or written. Then it installs the plugins one at a time, through the pipeline zeroclaw plugin install uses:

1. It resolves the package from the registry and refuses a registry entry that has no sha256 digest for its archive, before requesting the archive. zeroclaw plugin install checks the digest only when the registry lists one; Quickstart requires it.
2. It downloads and verifies the archive, confirms that the manifest provides a tool, admits the package, checks that its config entry can be seeded, and runs the install-time load check. When any of these steps fails, Quickstart reports it, writes nothing for that plugin, and moves on to the next one. The config entry check fails, for example, when the config still holds the plugin’s pre-1.0 entry, named only after the package, which zeroclaw plugin remove keeps: zeroclaw plugin install refuses to create an entry beside it, and Quickstart reports the same reason before it asks anything about the plugin. Quickstart has no --no-verify: for a plugin that fails the load check it prints the zeroclaw plugin install <name> --no-verify command, which installs a plugin that the daemon then skips at startup. That command is the plugin CLI, not Quickstart: it asks no signature question and no network access question, and a config entry it creates is seeded with the destinations the manifest declares for http_client.
3. It prints what the plugin is and what it asks for: name, version, author, description, capabilities, permissions, and the network destinations its manifest declares. Publisher text is stripped of terminal control sequences first.
4. It checks the manifest signature against plugins.security.trusted_publisher_keys, whatever plugins.security.signature_mode is, and adds one line to that summary: verified, with the first 16 characters of the trusted key; unsigned; signed under a key that is not trusted; or invalid. Unless the signature is verified, the author line is marked as the publisher’s own claim, and Quickstart asks whether to install the plugin anyway before any other question about it. The answer defaults to no, which skips the plugin and writes nothing. signature_mode still decides what admission refuses: in strict mode such a plugin is refused at step 2 instead. When Quickstart can read the plugins directory, a picked plugin that is already installed shows the same line, without the question.
5. For a plugin that requests http_client and declares destinations, you choose to grant the declared destinations, install without network access, or skip the plugin. The choice starts on installing without network access, so accepting it as offered grants nothing. Installing without network access creates the plugin’s config entry with an empty egress_hosts, so the plugin reaches nothing, and prints the exact zeroclaw config set command that grants the declared destinations later. It is the decision zeroclaw plugin bind --egress none records for a channel instance, and it prints the same command. A plugin that requests network access but declares no destinations gets no question; after installing it, Quickstart prints a zeroclaw config set --no-interactive command for the entry’s egress_hosts with no value: append the hosts your deployment uses as one comma-separated value. Run as printed, that command is refused for the missing value and writes nothing. A plugin that declares destinations and requests websocket_client or socket_client but not http_client gets no question either: its config entry grants none of them, and Quickstart prints the zeroclaw config set command that grants exactly those destinations.
6. For a plugin whose manifest has a config_schema, Quickstart prompts for the settings it describes: required properties first, optional ones only if you ask for them. Properties marked x-secret are masked as you type them, and spaces or line breaks around a secret value are dropped, as zeroclaw config set drops them. A value picked from a list is stored exactly as the schema lists it, an empty string included, while an empty typed answer leaves an optional setting unset. The values are checked against the schema before anything is written; after a failed check you get one more try, then Quickstart asks whether to install the plugin without them. Pressing Esc at a required setting that is secret or picked from a list skips the plugin. Quickstart prompts only for properties whose names are in the portable key grammar (up to 128 ASCII letters, digits, ., - and _). It names the others so that you can set them later with zeroclaw config set. When a required property is one of them, or a name the schema requires without declaring it, no answers could pass the check, so Quickstart asks for no settings and goes straight to asking whether to install the plugin without them. When the schema requires a name it does not declare, no config entry can satisfy it, whatever zeroclaw config set writes, so that question says the plugin’s tool would not be usable and asks whether to install it anyway.
7. It publishes the package and seeds its config entry in the same transaction zeroclaw plugin install uses, then saves the settings the way zeroclaw config set does. If seeding the entry fails, the transaction removes the package again. If that removal fails too, Quickstart says the plugin is still installed and prints the zeroclaw plugin remove command for it. If saving the settings fails, the plugin stays installed, and Quickstart prints the zeroclaw config set command for each setting, which asks for the value. A plugin that also provides a channel gets what zeroclaw plugin install prints for it: the zeroclaw plugin bind commands that bind an instance, or the readiness of the aliases that already bind the package. Quickstart binds no channel instance itself.

Values you type for settings that are not marked x-secret are echoed at the prompt, and a default from the schema is prefilled there. Setting values are never written to logs or to the status lines Quickstart prints; those name the settings only.

A plugin that is already installed is not downloaded, upgraded, or prompted for settings again. Quickstart only creates its config entry when that entry is missing. A new entry is a new grant, so for a plugin that requests http_client and declares destinations you first see what the plugin is and make the same choice as for a fresh install: grant the declared destinations, create the entry without network access, or skip, which leaves the entry absent and prints the command that creates it later. That command creates the entry without network access. The command that grants the declared destinations is printed on its own line, to run after it, so running a printed command never grants what you declined. Any other missing entry is seeded as zeroclaw plugin install seeds it. An existing entry is never changed, whether it belongs to an installed plugin or was left behind by an earlier install, so its egress grant and settings stay exactly as they are. Running Quickstart again with the same picks therefore downloads nothing and leaves those entries untouched. If Quickstart cannot finish setting up a plugin that is already installed, for example because the config still holds a pre-1.0 entry named only after the package or because saving the new entry fails, it writes nothing for that plugin and says that the plugin stays installed, with the reason.

After the last plugin, if at least one picked plugin is installed and plugins.enabled or plugins.auto_discover is off, Quickstart asks once whether to turn plugin activation on. First it lists which of those settings would change and everything that would become active as a result: every installed tool and skill plugin, including plugins installed before this run, and, when plugins.enabled is off, every enabled [channels.plugin.<alias>] channel. The list is read from the plugins directory, as a daemon would load it at its next start, so it also names a plugin whose failed install could not be undone. Each listed plugin whose signature is not verified is followed by its signature line from step 4, including a plugin this run did not pick. The answer defaults to yes when the list matches the plugins this run installed or kept, and to no when it would activate anything else, including an installed plugin whose missing config entry you chose to skip or that Quickstart could not finish setting up. If the plugins directory cannot be read, Quickstart says the list may be incomplete and the answer defaults to no. Declining leaves both settings unchanged and prints the zeroclaw config set commands that turn them on later. When both settings are already on, there is nothing to ask.

Once the agent is created, Quickstart prints the status of each picked plugin that is installed: admitted as a tool, with its config entry key, or the reason it is not admitted, such as plugins.enabled or plugins.auto_discover being off or the plugins.max_active_instances limit being reached. A plugin is reported admitted only when its config entry passes the settings check the runtime applies on every call. Admitted is not yet registered: the tool registry registers the plugin when it is next built, and it still refuses a package whose name clashes with a tool already registered, such as a built-in tool, or whose tool description it cannot read. The runtime log records those refusals. When the settings check fails instead, for example when you installed the plugin without its required settings, its status shows the reason the check gives, names the required settings that are missing, and prints the zeroclaw config set command that asks for each value. Quickstart prints commands only for setting names in the portable key grammar, which are safe to show and to paste into a shell. A required setting with any other name is named without a command: set it in the config file, or with a zeroclaw config set command you quote yourself. A required name that the plugin’s schema does not declare is named too, since no config entry can satisfy that schema until the plugin’s publisher fixes it. A plugin whose config entry is missing, for example because you skipped creating it, is not reported active either: zeroclaw config set only changes entries that exist, so its status prints the command that creates the entry instead. That command grants no network access; for a plugin that requests http_client and declares destinations, a separate line gives the command that grants them once the entry exists. When the config still holds the plugin’s pre-1.0 entry, named only after the package, its status prints neither command, since a new entry beside the old one would leave the old entry’s settings and network grant behind. It names the instance key to rename the old entry to instead. When zeroclaw plugin list prints the update steps for that entry, which it does for a plugin that requests http_client unless the deployment refuses every plugin’s network grant, the status also gives that command: its steps include any network grant the renamed entry still needs. A plugin with nothing to configure and no network access needs no config entry.

A picked plugin that was already installed may never have passed the load check, for example when it was installed with zeroclaw plugin install --no-verify, so Quickstart runs the check zeroclaw plugin info runs before it reports the plugin. When the plugin does not load against this host, ZeroClaw skips it at startup, so its status says that instead of calling it active and gives the zeroclaw plugin info command that shows why.

Quickstart writes the config file and never signals a running daemon. A daemon that is already running keeps the configuration it loaded, so the config entries, settings, network grants, and plugin activation changes a Quickstart run writes reach it only after it restarts or reloads its configuration. If plugin activation was already on in the configuration the daemon loaded, it can load a newly installed plugin sooner, the next time it builds its tool registry (for example for a new session). It then runs the plugin with the config entry it had loaded for that plugin, never one the run wrote: without one, the plugin has no settings and no network grant, and an older entry, such as one that zeroclaw plugin remove kept from an earlier install, applies with its settings and network grant. The status ends with the zeroclaw service restart command, addressed to the same configuration directory, which restarts a daemon that runs as the installed service. zeroclaw agent and other one-shot commands pick the changes up the next time they start.

Ctrl+C does not work the same everywhere in the plugin step. At a secret setting it works like Esc: at a required setting it cancels that plugin’s settings, so the plugin is skipped, and at an optional one it leaves the setting unset. Quickstart then carries on. Anywhere else in the step, Ctrl+C ends Quickstart at once, without a summary of what it already did. A plugin whose install finished stays installed and configured, and zeroclaw plugin list shows it. A plugin interrupted after its install but before its config entry was written stays installed without that entry; running Quickstart again with the same pick creates the entry, asking first when it would grant network destinations.

If the agent step still fails after the plugin step changed something, Quickstart does not claim that nothing changed. It names the plugins that stay installed, configured, or activated, and prints the zeroclaw plugin remove command for each plugin that run installed, including one whose failed install could not be undone and so stays in the plugins directory. Running Quickstart again does not reinstall them.

The architecture roadmap (FND-001, RFC #5574, deliverable D4) asks for zeroclaw onboard to install plugins. zeroclaw quickstart, the maintained command that zeroclaw onboard now points to, delivers that for tool plugins, in builds with plugin support. Installing channel plugins during onboarding and shipping release artifacts with plugin support are separate deliverables.

zerocode

In the zerocode terminal interface, the Quickstart pane is one of the tabs. Drive it with the keyboard:

Switch to the Quickstart pane:

You can also choose » Quickstart in the agent sidebar. Pressing Esc returns to the pane that opened Quickstart, whether you entered from the keyboard mode bar, a mode-bar click, or the sidebar launcher.

Inside the pane:

Mouse works too: click a tab in the mode bar to switch panes, click a step to select and open it, and scroll to move through the list.

Each step opens a modal that mirrors the checklist above, with a “Use existing” option that lists the matching aliases already in your config.

Web gateway

With the daemon running, open the dashboard in a browser:

zeroclaw daemon

zeroclaw daemon runs the full runtime: the gateway, your configured channels, the scheduler, and the heartbeat monitor. (zeroclaw gateway starts only the HTTP gateway if that is all you need.)

Then visit http://127.0.0.1:42617/quickstart. A fresh install with no agents configured redirects there automatically; afterward you can always reach it from the dashboard navigation.

The web form presents the same steps as cards. On submit it applies your submission through the daemon (POST /api/quickstart/apply), which returns a structured error list if anything is invalid, then reloads the daemon in place so the new agent is live without a restart. A separate POST /api/quickstart/validate endpoint runs the same checks without applying, for clients that want to validate first.

After Quickstart

• Drive it from zerocode: the terminal interface is the best way to chat, watch live logs, manage config, and monitor the daemon, all in one place. Just run zerocode.
• Quick one-off from the shell: zeroclaw agent -a <alias> -m "your message".
• Run always-on: zeroclaw service install && zeroclaw service start.
• Add channels later: Channels → Overview.
• Tune autonomy and budgets: Reference → Config.