Clawrium

---

Support matrix

What	Supported today	Notes
Control machine OS	Ubuntu, macOS	Tested end-to-end
Target host OS	Ubuntu, macOS	macOS hosts must enable Remote Login first (host setup)
Agent runtimes	OpenClaw ✅, Hermes ✅, ZeroClaw ✅, Claude Code ✅	Claude Code has on-demand CLI and GUI chat (no daemon or native web UI); IronClaw planned
Inference providers	Anthropic, OpenAI, OpenRouter, Ollama	Claude Code accepts an Anthropic API key or explicitly supplied OAuth token
Messaging channels	Discord, Slack	OpenClaw only
Container runtime	None required	No Docker, no Kubernetes — SSH + Ansible

How it works

Clawrium uses Ansible under the hood for SSH-based orchestration. You run clawctl from your control machine, which talks to target hosts over SSH. No agents, no containers, no Kubernetes complexity - just processes running on hosts with a unified management layer.

Why Clawrium

You're running multiple AI agents - coding assistants, internal tools, experiment harnesses - across machines on your network. Without Clawrium, you SSH into each box, manage configs individually, lose track of token spend, and have no unified view of what's running where.

Clawrium gives you kubectl-style fleet control for AI agents:

• One CLI, all hosts. Add machines to your fleet and deploy any agent type to any host.
• Specialized agents. Each agent does one job and does it well. Instead of one overloaded assistant, run a fleet of purpose-built agents - a coding agent, a review agent, a research agent - each with its own context, data, and configuration isolated from the rest.
• Local inference. Use hardware you already have - Mac Minis, NVIDIA DGX Spark, spare servers - as inference providers. Run smaller open models like Gemma, GPT-4o-mini, Kimi, or Llama locally and point multiple agents at them.
• Model experimentation. Swap models across agents to compare performance without touching individual configs.
• Lifecycle management. Upgrades, rollbacks, secrets rotation, backups - handled.
• Token tracking & guardrails. See spend across your fleet. Set limits before someone's experiment burns through your API budget.

What is an Agent?

A Clawrium agent is a general-purpose AI assistant that runs on a host in your network. Unlike coding-focused assistants (Copilot, Cursor), these agents are designed for broader tasks. Agent implementations:

• OpenClaw ✅ - Open-source general assistant
• Hermes ✅ (Nous Research) - OpenAI-compatible local API
• ZeroClaw ✅ - Lightweight assistant for resource-constrained hosts
• Claude Code ✅ - Isolated, install-only command environment; see Claude Code Support
• IronClaw (planned) - High-performance assistant for demanding workloads

Clawrium manages installation and configuration for every supported agent, and daemon lifecycle operations for agent types that provide a managed daemon. Claude Code intentionally remains an install-only, no-daemon command environment.

Who this is for

Clawrium is for engineers running AI agents in non-trivial setups - home labs, dev teams, research groups. If you have more than one agent running on more than one machine, this tool exists for you.

It is not a hosted platform. There's no dashboard, no SaaS, no account signup. It's a Python CLI that talks to your machines via Ansible. You own everything.

Quickstart

What You'll Need

Requirement	Why
Python 3.10+	Runtime for clawctl CLI
uv	Fast Python package installer
SSH access to a remote host	Clawrium manages agents over SSH
API key (Anthropic, OpenAI, etc.)	Agents need inference providers

Install & Run

# Install
uv tool install clawrium

# Or run without installing
uvx --from clawrium clawctl --help

For full installation instructions including how to install uv, see docs/installation.md.

5-Minute Setup

Step 1 — On your control machine: initialize Clawrium

clawctl service init

Step 2 — On your control machine: generate the xclm setup commands for the host

clawctl host create 192.168.1.100 --user xclm --alias worker-1

This generates a per-host SSH keypair and, because the xclm user doesn't exist on the host yet, prints the exact setup block (Linux and macOS variants) with your fresh public key inlined. Example output (Linux):

## Linux
# Create xclm user
sudo useradd -m -s /bin/bash xclm
# Passwordless sudo
echo "xclm ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/xclm
sudo chmod 440 /etc/sudoers.d/xclm
# Authorized key
sudo mkdir -p /home/xclm/.ssh && sudo chmod 700 /home/xclm/.ssh
echo 'ssh-ed25519 AAAA…' | sudo tee /home/xclm/.ssh/authorized_keys
sudo chmod 600 /home/xclm/.ssh/authorized_keys
sudo chown -R xclm:xclm /home/xclm/.ssh

Step 3 — SSH into the host and paste the printed block

ssh [email protected]   # log in as any sudo-capable user
# paste the block from Step 2, exit

(Full Linux + macOS variants and rationale: docs/host-preparation.md.)

Step 4 — On your control machine: re-run clawctl host create to register the host

clawctl host create 192.168.1.100 --user xclm --alias worker-1
# → host/worker-1 registered (xclm verified)

Step 5 — Register a provider, install + start the agent

# Inference provider
clawctl provider registry create anthropic --type anthropic --api-key-stdin

# Install, configure, and start an OpenClaw agent
clawctl agent create my-assistant --type openclaw --host worker-1 --provider anthropic
clawctl agent configure my-assistant
clawctl agent start my-assistant

# Check fleet status
clawctl agent get
# NAME           TYPE       HOST       PROVIDER    STATUS    AGE
# my-assistant   openclaw   worker-1   anthropic   running   2m

# Chat with your agent
clawctl agent chat my-assistant

# Or open the local web dashboard
clawctl gui

You should see: A running agent in clawctl agent get output with status running.

→ Full setup guide: ric03uec.github.io/clawrium

Key Concepts

Concept	What it is
Host	A machine in your network running one or more agents
Agent	An installed AI assistant instance managed by Clawrium
Agent Type	The implementation/runtime class of an agent
Agent Name	The unique identifier for an installed agent instance
Registry	Platform-defined agent types with versions, dependencies, and templates

FAQ

1. What operating systems are supported?

Ubuntu and macOS are in the test matrix — both as the control machine and as target hosts. On macOS hosts you must enable Remote Login before registering them; see docs/host-preparation.md. Other Linux distributions may work but aren't tested.

2. Which agents are supported today?

OpenClaw is officially supported and tested end-to-end.

Hermes (Nous Research) is supported in 🚧 In Development status — install, configure, and a local OpenAI-compatible HTTP API on 127.0.0.1:8642 are wired end-to-end. clawctl agent chat and external messaging gateways are not yet supported for hermes. See the Hermes Support Matrix for details.

Additional agent types are planned.

3. Is Claude Code authentication supported?

Claude Code uses exactly one per-agent credential mode: an Anthropic API key or a native OAuth document. API keys are supplied through the agent secret CLI; OAuth is imported only from the controller's exact private ~/.claude/.credentials.json artifact on supported Linux controllers. Clawrium does not read keychains, browser profiles, databases, or scan local credential directories. See Claude Code Support.

4. Which channels are supported?

Discord and Slack are supported for OpenClaw.

Additional channels are planned.

5. Does Clawrium install Docker or Kubernetes?

No. Clawrium does not require Docker or Kubernetes. It manages agent processes over SSH using Ansible.

6. Can I manage multiple hosts with different agent types?

Yes. You can register multiple hosts and run different agent types on each host from the same clawctl control node.

7. Why doesn't it support x-agent and y-feature?

I'm building Clawrium in my spare time, so I prioritize my own use cases first.

If you want support for a specific agent type or feature, please open an issue and send a PR. See CONTRIBUTING.md for contribution guidelines.

8. Why not Kubernetes?

Two reasons:

1. Most AI agent runtimes don't support it. These run as local processes, not containerized services. They expect a home directory, local config files, and direct access to the host. Wrapping them in containers adds friction with no payoff.

2. K8s is overkill for local fleets. You're managing 3-10 machines on a LAN, not orchestrating microservices across cloud regions. Kubernetes brings etcd, control planes, networking overlays, RBAC, and a learning curve that dwarfs the problem. You don't need a container scheduler - you need to SSH into a box and run a process.

Clawrium uses Ansible under the hood instead. Ansible gives you idempotent host management, secrets handling, and multi-machine orchestration without requiring anything on the target machines beyond SSH. Clawrium sits on top of Ansible and adds the agent-specific layer: lifecycle management, token tracking, model swapping, and fleet-wide visibility.

Tech Stack

Python · Typer · ansible-runner · uv

Contributing

git clone https://github.com/ric03uec/clawrium && cd clawrium
make test       # Run tests
make lint       # Check style
make format     # Auto-format

Issues are the source of truth. See CONTRIBUTING.md for the full workflow.

Changelog

Changes for the current, unreleased version are tracked in CHANGELOG.md. Every shipped release is archived under docs/releases/<version>/, which is the single place to read the full history of what changed in any release.

License

Apache 2.0