This guide provides an Ansible playbook to deploy ZeroClaw natively (without Docker) on Debian 10+, Ubuntu 20.04+, and RHEL 9+ compatible hosts using pre-built static binaries. ZeroClaw is an ultra-lightweight Rust AI agent runtime designed for edge devices and resource-constrained environments.
Important: ZeroClaw uses file-based configuration stored in ~/.zeroclaw/config.toml. No external database is required.
Official Resources:
Note: Between March 30 and April 2, 2026, the zeroclaw-labs GitHub organization went offline (404 errors) and was subsequently restored.
- name: Deploy ZeroClaw (Native Binary Installation)
hosts: zeroclaw
become: true
vars:
# Application settings
zeroclaw_user: zeroclaw
zeroclaw_home: /home/zeroclaw
zeroclaw_version: "latest"
zeroclaw_install_dir: /opt/zeroclaw
# Gateway settings
gateway_port: 3000
gateway_host: "127.0.0.1"
# Provider settings
zeroclaw_provider: openai
zeroclaw_api_key: "{{ vault_zeroclaw_api_key }}"
zeroclaw_channels: ['cli']
# Architecture detection
zeroclaw_arch_map:
x86_64: "x86_64"
aarch64: "aarch64"
armv7l: "armv7"
tasks:
- name: Get architecture
set_fact:
zeroclaw_arch: "{{ zeroclaw_arch_map[ansible_architecture] | default(ansible_architecture) }}"
- name: Get OS family
set_fact:
zeroclaw_os: >-
{% if ansible_system == 'Linux' %}
{% if ansible_architecture == 'aarch64' %}aarch64-unknown-linux-gnu
{% elif ansible_architecture == 'armv7l' %}armv7-unknown-linux-gnueabihf
{% else %}x86_64-unknown-linux-gnu
{% endif %}
{% elif ansible_system == 'Darwin' %}
{% if ansible_architecture == 'aarch64' or ansible_architecture == 'arm64' %}aarch64-apple-darwin
{% else %}x86_64-apple-darwin
{% endif %}
{% else %}
{{ ansible_system | lower }}
{% endif %}
- name: Install prerequisites (Debian/Ubuntu)
apt:
name:
- curl
- ca-certificates
state: present
update_cache: true
when: ansible_os_family == "Debian"
- name: Install prerequisites (RHEL)
dnf:
name:
- curl
- ca-certificates
state: present
when: ansible_os_family == "RedHat"
- name: Create ZeroClaw system user
user:
name: "{{ zeroclaw_user }}"
home: "{{ zeroclaw_home }}"
shell: /bin/bash
system: true
create_home: true
comment: "ZeroClaw AI Agent Service"
- name: Create installation directory
file:
path: "{{ zeroclaw_install_dir }}"
state: directory
mode: "0755"
owner: "{{ zeroclaw_user }}"
group: "{{ zeroclaw_user }}"
- name: Get latest ZeroClaw release info
uri:
url: "https://api.github.com/repos/zeroclaw-labs/zeroclaw/releases/latest"
method: GET
return_content: true
register: release_info
changed_when: false
delegate_to: localhost
run_once: true
- name: Set ZeroClaw version
set_fact:
zeroclaw_version: "{{ release_info.json.tag_name | default('latest') | regex_replace('^v', '') }}"
- name: Build download URL
set_fact:
zeroclaw_download_url: "https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-{{ zeroclaw_os }}.tar.gz"
- name: Download ZeroClaw binary
get_url:
url: "{{ zeroclaw_download_url }}"
dest: "/tmp/zeroclaw-{{ zeroclaw_version }}.tar.gz"
mode: "0644"
become: false
delegate_to: localhost
run_once: true
- name: Extract and install ZeroClaw binary
unarchive:
src: "/tmp/zeroclaw-{{ zeroclaw_version }}.tar.gz"
dest: "{{ zeroclaw_install_dir }}"
remote_src: false
owner: "{{ zeroclaw_user }}"
group: "{{ zeroclaw_user }}"
delegate_to: localhost
run_once: true
- name: Copy binary to target host
copy:
src: "/tmp/zeroclaw"
dest: "{{ zeroclaw_install_dir }}/zeroclaw"
mode: "0755"
owner: "{{ zeroclaw_user }}"
group: "{{ zeroclaw_user }}"
- name: Create symlink in /usr/local/bin
file:
src: "{{ zeroclaw_install_dir }}/zeroclaw"
dest: /usr/local/bin/zeroclaw
state: link
- name: Create .zeroclaw directory
file:
path: "{{ zeroclaw_home }}/.zeroclaw"
state: directory
mode: "0700"
owner: "{{ zeroclaw_user }}"
group: "{{ zeroclaw_user }}"
- name: Generate API key encryption secret
command: openssl rand -hex 32
register: secret_key
changed_when: false
no_log: true
- name: Write secret key file
copy:
dest: "{{ zeroclaw_home }}/.zeroclaw/.secret_key"
mode: "0600"
owner: "{{ zeroclaw_user }}"
group: "{{ zeroclaw_user }}"
content: "{{ secret_key.stdout }}"
no_log: true
- name: Write ZeroClaw configuration file
copy:
dest: "{{ zeroclaw_home }}/.zeroclaw/config.toml"
mode: "0600"
owner: "{{ zeroclaw_user }}"
group: "{{ zeroclaw_user }}"
content: |
# ZeroClaw Configuration
api_key = '{{ zeroclaw_api_key }}'
provider = '{{ zeroclaw_provider }}'
channels = {{ zeroclaw_channels | to_json }}
workspace_only = true
log_level = 'info'
# Gateway settings
[gateway]
port = {{ gateway_port }}
host = '{{ gateway_host }}'
require_pairing = true
allow_public_bind = false
# Memory system
[memory]
backend = "sqlite"
auto_save = true
embedding_provider = "none"
# Autonomy and security
[autonomy]
level = "supervised"
workspace_only = true
allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep"]
forbidden_paths = ["/etc", "/root", "/proc", "/sys"]
- name: Create systemd service file
copy:
dest: /etc/systemd/system/zeroclaw.service
mode: "0644"
content: |
[Unit]
Description=ZeroClaw AI Agent Runtime
After=network.target
Documentation=https://github.com/zeroclaw-labs/zeroclaw
[Service]
Type=simple
User={{ zeroclaw_user }}
Group={{ zeroclaw_user }}
WorkingDirectory={{ zeroclaw_home }}
Environment=HOME={{ zeroclaw_home }}
ExecStart={{ zeroclaw_install_dir }}/zeroclaw daemon
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths={{ zeroclaw_home }}/.zeroclaw
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
[Install]
WantedBy=multi-user.target
- name: Reload systemd daemon
systemd:
daemon_reload: true
- name: Enable ZeroClaw service
systemd:
name: zeroclaw
enabled: true
daemon_reload: true
- name: Start ZeroClaw service
systemd:
name: zeroclaw
state: started
- name: Wait for ZeroClaw to be ready
wait_for:
port: "{{ gateway_port }}"
host: "{{ gateway_host }}"
timeout: 30
ignore_errors: true
- name: Display deployment information
debug:
msg: |
ZeroClaw deployment complete!
Service Status: Active
Gateway Port: {{ gateway_port }}
Gateway Host: {{ gateway_host }}
Version: {{ zeroclaw_version }}
IMPORTANT:
- ZeroClaw binds to {{ gateway_host }}:{{ gateway_port }} by default
- Store API keys securely in ~/.zeroclaw/config.toml
- Run 'zeroclaw doctor' for health checks
- See 'zeroclaw onboard --interactive' for guided setup
Save the playbook as deploy-zeroclaw-native.yml.
Create an inventory file (inventory.ini):
[zeroclaw]
server1.example.com
server2.example.com
[zeroclaw:vars]
ansible_user=deploy
ansible_ssh_private_key_file=~/.ssh/id_ed25519
Use Ansible Vault to store sensitive values:
# Create vault file
ansible-vault create group_vars/zeroclaw/vault.yml
Add your API key:
vault_zeroclaw_api_key: "sk-your-actual-api-key-here"
# Basic run
ansible-playbook -i inventory.ini deploy-zeroclaw-native.yml
# With vault
ansible-playbook -i inventory.ini deploy-zeroclaw-native.yml --ask-vault-pass
~/.zeroclaw/config.toml~/.zeroclaw/.secret_key)| Variable | Description | Default |
|---|---|---|
zeroclaw_user |
System user for ZeroClaw | zeroclaw |
zeroclaw_home |
Home directory | /home/zeroclaw |
zeroclaw_install_dir |
Installation directory | /opt/zeroclaw |
gateway_port |
Gateway port | 3000 |
gateway_host |
Gateway bind address | 127.0.0.1 |
zeroclaw_provider |
AI provider | openai |
zeroclaw_api_key |
Provider API key (use Ansible Vault) | Required |
zeroclaw_channels |
List of channels to enable | ['cli'] |
| Provider | Config Value | Notes |
|---|---|---|
| OpenAI | openai |
GPT-4, GPT-3.5-turbo |
| Anthropic | anthropic |
Claude models |
| OpenRouter | openrouter |
Multi-provider aggregator |
| Ollama | ollama |
Local models |
| llama.cpp | llama.cpp |
Local llama-server |
| vLLM | vllm |
Local vLLM server |
| Osaurus | osaurus |
macOS edge runtime |
| OpenAI Codex | codex |
ChatGPT subscription OAuth |
| Custom | custom |
OpenAI-compatible endpoints |
# Check systemd status
systemctl status zeroclaw
# View logs
journalctl -u zeroclaw -f
# Test the installation
zeroclaw --version
zeroclaw doctor
By default, ZeroClaw binds to localhost on port 3000:
# SSH to server and test
ssh user@server
curl http://127.0.0.1:3000
Edit the configuration file:
# SSH to server
ssh user@server
# Switch to zeroclaw user
sudo su - zeroclaw
# Edit config
nano ~/.zeroclaw/config.toml
# Restart service
sudo systemctl restart zeroclaw
For interactive setup:
sudo su - zeroclaw
zeroclaw onboard --interactive
systemctl status zeroclaw
# Full logs
journalctl -u zeroclaw -f
# Last 100 lines
journalctl -u zeroclaw -n 100
# Since boot
journalctl -u zeroclaw -b
systemctl restart zeroclaw
systemctl stop zeroclaw
# Download latest binary
curl -fsSLO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-x86_64-unknown-linux-gnu.tar.gz
# Extract and replace
tar xzf zeroclaw-*.tar.gz
sudo install -m 0755 zeroclaw /opt/zeroclaw/zeroclaw
# Restart service
sudo systemctl restart zeroclaw
systemctl status zeroclaw
journalctl -u zeroclaw -f
sudo su - zeroclaw
zeroclaw doctor
zeroclaw status
sudo su - zeroclaw
zeroclaw test --config ~/.zeroclaw/config.toml
sudo su - zeroclaw
zeroclaw daemon
zeroclaw --version
zeroclaw --help
zeroclaw doctor regularly for security auditsjournalctl -u zeroclawFor detailed security guidance, see ZeroClaw Security.
Beyond this playbook, we offer:
Contact our automation team: office@linux-server-admin.com