How to Deploy ZeroClaw

ZeroClaw is one of those projects that looks intimidating from a distance and surprisingly manageable once you understand what it actually is. It is a self-hosted AI assistant runtime you run on your own machine, with a gateway, a web dashboard, channel integrations, local workspace state, and a CLI that handles both testing and always-on operation.

For a beginner, deployment is really three jobs disguised as one:

1. Install the binary
2. Run onboarding so ZeroClaw creates and validates your workspace and provider config
3. Decide whether you want a test deployment or a persistent one

That distinction matters. Most beginner pain starts when people skip it — either thinking they are "deploying ZeroClaw" when they are really just opening a local binary once, or assuming they need a cloud server on day one when they usually do not. The cleanest beginner deployment starts on your own machine first. The project's own docs push that route.

The key runtime pieces

ZeroClaw is not just a chatbot CLI. The official repository describes it as a personal AI assistant you run on your own devices, with support for many messaging channels and a web dashboard for control. It can run as a lightweight local process, but it also supports service-style deployment so it stays online and handles channels continuously.

If you understand those five pieces, you understand deployment.

What you need before you start

ZeroClaw's README says the runtime uses the Rust stable toolchain and ships as a single binary with no runtime dependencies. The project currently supports onboarding on macOS, Linux, and Windows through WSL2.

Your real checklist before installing:

• A supported OS (macOS, Linux, or Windows via WSL2)
• Shell access
• A provider plan or API key (OpenAI Codex, Gemini, Anthropic, or OpenRouter)
• Permission to run a local service if you want always-on behavior

The config reference lists openrouter as the default provider and anthropic/claude-sonnet-4-6 as the default model routed through the selected provider.

Note for Windows users: There is an open bug report about installation problems on Ubuntu 18.04 and 24.04 inside WSL2, so treat WSL2 support as real but not entirely frictionless yet.

Step 1: Install ZeroClaw

Option A — Homebrew (macOS or Linuxbrew)

The simplest install route:

brew install zeroclaw

This is the most beginner-friendly path when it works on your machine.

Option B — One-click bootstrap from source

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

The docs say zeroclaw onboard runs automatically after install to configure the workspace and provider.

Option C — Build from source

Use this if the packaged install fails or you want tighter control:

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo build --release --locked
cargo install --path . --force --locked
zeroclaw onboard

The repo also notes a development fallback where you can skip global installation and prefix commands with cargo run --release --.

Which option should a beginner choose? Use Homebrew first if you are on macOS. Use ./install.sh second. Use source build only if you hit package issues or want tighter control. That recommendation matches the project's own "recommended install" posture around the bootstrap flow and guided onboarding.

Step 2: Run onboarding properly

This is the step beginners are most likely to underrate. The getting started docs explicitly describe onboarding as the place where you set up the provider, workspace, and channels.

For most beginners, the right command is either:

zeroclaw onboard --interactive

Or, if you already know your provider and key:

zeroclaw onboard --api-key "sk-..." --provider openrouter

Other available modes:

• --channels-only — fix channel config without touching the rest
• --force — full overwrite of existing config

The guide notes that reruns protect existing config unless you explicitly confirm or use --force. That matters because many people rerun setup casually and accidentally wipe a working configuration.

What onboarding is doing behind the scenes

ZeroClaw resolves config from, in order:

1. ZEROCLAW_WORKSPACE if set
2. A persisted ~/.zeroclaw/active_workspace.toml marker if present
3. The default ~/.zeroclaw/config.toml path

That means your deployment is not just the binary — it is also the workspace and config resolution path. If you move machines, switch shells, or install a service without understanding where config lives, you can end up starting the right binary with the wrong configuration.

Step 3: Validate before you "deploy"

The official docs repeatedly point beginners to two commands after onboarding:

zeroclaw status
zeroclaw doctor

Do not skip this. If status or doctor are already unhappy, turning the runtime into a background service will only make the problem harder to trace.

Also send a single test prompt:

zeroclaw agent -m "Hello, ZeroClaw!"

That confirms the model provider is actually usable, not just present in a config file. The README includes this exact pattern as part of the quick start.

Step 4: Start the gateway for local testing

zeroclaw gateway

By default it binds to 127.0.0.1:42617. You can also randomize the port with --port 0, which the README calls out as a security-hardened option.

The gateway lets you validate the web dashboard and local runtime behavior without committing to full daemon mode. It answers the only question that matters in the early phase: does this install actually work on this machine with this provider and this config? If yes, move on. If no, fix it before touching channels or services.

Step 5: Move to daemon mode for real deployment

Once local testing works, launch the full runtime:

zeroclaw daemon

The CLI documentation states that daemon mode launches the gateway server, all configured channels, the heartbeat monitor, and the cron scheduler. The repo describes this as the recommended mode for production or an always-on assistant. This is the point where ZeroClaw becomes something closer to an actual deployment and not just a shell session.

Step 6: Install ZeroClaw as a service

Once daemon mode works manually, only then should you install it as a service:

zeroclaw service install
zeroclaw service start
zeroclaw service status

The repo describes service install as registering the daemon as an OS service for auto-start on boot using launchd or systemd. Recent release notes also mention service log support across systemd, launchd, and Windows.

Running zeroclaw daemon in a terminal is fine for testing — it is not a durable deployment. Close the terminal, lose the process. A service install gives you startup at boot, restart control, OS-native lifecycle management, and cleaner operational handling. That is what makes ZeroClaw feel like infrastructure instead of a demo.

Linux deployment

On Linux, the docs and CLI point to service-based deployment for persistent runtime management. There is also explicit documentation for OpenRC environments such as Alpine:

sudo zeroclaw service install
sudo rc-update add zeroclaw default
sudo rc-service zeroclaw start
sudo rc-service zeroclaw status

The same docs say that service install usually handles migration of runtime state from your user setup into /etc/zeroclaw and fixes permissions for the zeroclaw service user. If no prior runtime state exists, you must create /etc/zeroclaw/config.toml before starting the service.

That is a crucial detail. Beginners often assume the service sees the same home-directory config they just tested interactively. Sometimes it does through migration — sometimes you need to confirm what got copied and where. Deploy interactively first. Then install as a service. Then verify the service is reading the config you expect.

macOS deployment

The service layer supports launchd-based OS service installation. The best macOS path is:

brew install zeroclaw
zeroclaw onboard --interactive
zeroclaw status
zeroclaw doctor
zeroclaw gateway
zeroclaw daemon
zeroclaw service install

macOS users often try to jump directly to background launchd behavior before confirming the provider and dashboard work normally in the foreground. That is backwards. Recent release notes also mention macOS sandbox-exec profiles being added, which is relevant if you care about tighter host-side control later — but it is not a beginner prerequisite.

Windows deployment

The repo says the recommended setup works on Windows via WSL2, and recent release notes mention a Windows setup batch file and service log support for Windows. That said, the existence of a recent open install bug affecting Ubuntu versions inside WSL2 is your warning not to oversimplify the process.

If you are on Windows: start with a clean WSL2 shell, complete onboarding, run status and doctor, then use the agent and gateway first. Do not start by trying to harden it into a background service.

Android deployment

ZeroClaw's docs do cover Android. The Android setup guide recommends Termux services for daemon mode, notes storage permission requirements, and mentions that some features may need Android VPN permission for local binding. It also documents both on-device builds in Termux and cross-compiles with the Android NDK.

That is real support, but not the right beginner deployment target unless mobile is the entire point. Deploy on macOS or Linux first, then port.

How configuration works

A lot of deployment pain comes from not knowing which config file is live. The docs say startup resolves config through workspace override, active workspace marker, then default config path — and that ZeroClaw logs the resolved path, workspace, source, and initialized state at startup.

That means when debugging deployment, you should not guess. Start the process, read the startup logs, and confirm the loaded config path.

The config reference lists core defaults:

default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-6"
default_temperature = 0.7

Those defaults may be fine, but a beginner should still make them explicit during onboarding so the deployment is understandable six days later.

When to add channels

ZeroClaw supports a broad set of channels including Telegram, Slack, Discord, WhatsApp, Matrix, and email. Channel settings live under channels_config in ~/.zeroclaw/config.toml, and each channel is enabled by creating its sub-table.

For beginners, the rule is simple: do not enable channels until local chat works. That means zeroclaw agent works, zeroclaw gateway works, and zeroclaw daemon works — only then do you bind channels.

Why? Because channel problems are often not channel problems. They are provider, config, token, or stale-runtime problems wearing a channel costume. The channels docs even call out stale runtime state and missing restarts as a common source of "no reply" symptoms.

Should you deploy on a VPS or a local machine first?

For a beginner: local machine first, every time.

The official architecture is clearly comfortable running on your own devices. The gateway defaults to local loopback, onboarding is optimized for direct terminal use, and persistent service installation comes after you already have a working runtime.

A VPS makes sense later if you need:

• A permanently reachable external webhook endpoint
• Centralized uptime
• Multi-device access patterns
• Channel integrations that benefit from server-style exposure

But that is phase two, not day one.

Security and operational reality

ZeroClaw is lightweight and fast, but "easy to deploy" does not mean "safe by default in every network shape." The docs include dedicated security and network deployment material, and recent releases added mutual TLS for high-security deployments, WebAuthn or hardware key authentication, and plugin signature verification. That signals a project actively growing into more serious operational use.

The beginner takeaway is straightforward:

• Keep your first deployment local
• Use loopback binding first
• Do not expose the gateway publicly until you understand the network model
• Add one integration at a time
• Recheck with status, doctor, and channel-specific diagnostics after each change

Final thoughts

The reason ZeroClaw deployment feels harder than it is comes down to naming. People hear "AI assistant infrastructure" and imagine Kubernetes, reverse proxies, cloud queues, and twelve layers of pain. But the official project flow is much more grounded: install the binary, onboard the provider, validate the runtime, start the gateway, graduate to daemon mode, then convert it into a service.

If you are a beginner, that is your edge. Stay boring. Stay sequential. Treat deployment as a ladder, not a leap.

ZeroClaw is designed to be deployable in small steps. The mistake is not that it is too technical — the mistake is trying to do all of it at once.

What is the easiest way to deploy ZeroClaw as a beginner?

Use the official guided path: install it, run zeroclaw onboard, validate with zeroclaw status and zeroclaw doctor, test with zeroclaw gateway, then move to zeroclaw daemon. That is the project's recommended setup pattern.

Do I need a cloud server to deploy ZeroClaw?

No. The official docs frame ZeroClaw as something you run on your own devices, and the gateway defaults to a local loopback address. A local-first deployment is the right beginner move.

What is the difference between gateway and daemon?

gateway starts the local gateway server and dashboard. daemon starts the full runtime — including the gateway, configured channels, heartbeat monitor, and scheduler. The project recommends daemon mode for production or always-on use.

How do I keep ZeroClaw running after reboot?

Install it as an OS service:

zeroclaw service install

Then manage it with zeroclaw service start|stop|restart|status. The CLI documents support for systemd and launchd, and recent release notes mention service logs across systemd, launchd, and Windows.

Where is ZeroClaw's config stored?

Startup resolves config from ZEROCLAW_WORKSPACE, then ~/.zeroclaw/active_workspace.toml, then ~/.zeroclaw/config.toml. ZeroClaw also logs the resolved config path, workspace, source, and initialized state at startup — so you never have to guess which file is live.

Should I add Telegram, Discord, or other channels during initial deployment?

No. Get local CLI and gateway behavior working first. No-reply issues in channels often come from config problems, allowlist mismatches, stale runtime state, or missing restarts — not the channel itself.

Is Windows supported?

Yes, via WSL2 according to the official README, but there is a recent open issue about installation problems on some Ubuntu versions inside WSL2. Support exists, but some setups may still need troubleshooting.

Can I deploy ZeroClaw on Android?

Yes. The docs cover Android through Termux or ADB-based paths, but Android has limitations — no systemd, some permission caveats. It is supported, but not the simplest beginner starting point.

What should I run after updating ZeroClaw?

zeroclaw doctor

The README explicitly recommends this after updates.

What release is current?

The GitHub releases page shows v0.6.3 published on March 26, 2026, with changes including Windows setup batch support, service logs, mutual TLS, and other runtime features.