An immutable, AI-native Linux OS where autonomous agents run in hardened Firecracker microVMs.
Architecture • Quick Start • Phases • Building • Configuration • Contributing
ClawOS is a production-grade NixOS-based operating system designed to run autonomous AI agents in isolated, verifiable, and observable environments.
Each agent gets its own Firecracker microVM with:
- Immutable rootfs — dm-verity protected, read-only agent image
- Chain-of-trust boot — Ed25519 signed kernel + root hash (Phase 3)
- eBPF syscall monitoring — every system call recorded and audited
- LLM proxy layer — per-agent rate limiting and token usage tracking
- Zero-trust identity — Ed25519 JWT issued per agent, AES-256-GCM key storage
- Full observability — CEF syslog for SIEM integration, JSONL audit logs
┌─────────────────────────────────────────────────────────────────┐
│ ClawOS Host (NixOS, hardened kernel + KVM) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ vm-launcher │ │ orchestrator │ │ control-plane │ │
│ │ :2080 │ │ :2081 │ │ :8080 (+ TLS) │ │
│ └──────┬───────┘ └──────────────┘ └─────────────────────┘ │
│ │ │
│ ┌──────▼──────────────────────────────────────────────────┐ │
│ │ VM bridge clawos-br0 (10.0.0.1/24) │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ inference-proxy :11435 (rate limit + tokens) │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────▼────────────────────────────────────────────────────┐ │
│ │ Agent VMs (Firecracker microVMs, KVM, NixOS guest) │ │
│ │ │ │
│ │ vda: rootfs.img (ro, dm-verity) │ │
│ │ vdb: runtime.img (rw, /var) │ │
│ │ vdc: workspace.img (rw, /workspace) │ │
│ │ │ │
│ │ openclaw-gateway :18789 ← CLI / orchestrator │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ eBPF monitor │ │ identity- │ │ skill-manager │ │
│ │ (libbpf, C) │ │ manager │ │ (plugin host) │ │
│ │ → JSONL + CEF │ │ :2082 │ │ │ │
│ └──────────────────┘ └──────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
| Service | Port | Description |
|---|---|---|
vm-launcher |
2080 | Firecracker VM lifecycle daemon |
orchestrator |
2081 | Multi-agent workflow engine |
identity-manager |
2082 | Ed25519 JWT + SAML/OIDC |
control-plane |
8080 | REST API gateway (nginx TLS) |
inference-proxy |
11435 | LLM proxy (rate limit + audit) |
monitor-daemon |
— | eBPF syscall monitor → JSONL/CEF |
clawos-cli |
— | CLI (clawos vm start/stop/list) |
- NixOS (or Linux with Nix + flakes) with KVM enabled
- WSL2: set
nestedVirtualization=truein~/.wslconfig
# Enable Nix flakes (NixOS-WSL)
nix.settings.experimental-features = [ "nix-command" "flakes" ];# 1. Clone
git clone https://github.com/mmmykola/clawos
cd clawos
# 2. Enter the dev shell
nix develop
# 3. Build all Go binaries
make build-go
# 4. Build the agent VM NixOS image
make build-image
# 5. Build the eBPF monitor
make monitor
# 6. Run unit tests
make test-unit
# 7. Deploy the NixOS host configuration
sudo nixos-rebuild switch --flake .#clawos-host# Start a new agent VM
clawos vm start my-agent --model claude-haiku-4-5-20251001 --mem 512
# List running agents
clawos vm list
# Stop an agent
clawos vm stop my-agent- Firecracker microVM launcher (Go,
vm/) - eBPF syscall monitor (C + libbpf,
observability/) - CLI (
cli/) - NixOS agent VM image with dm-verity rootfs
- Bridge networking (
clawos-br0, 10.0.0.0/24)
- Multi-agent orchestrator (
orchestrator/) - Zero-trust identity manager — Ed25519 JWT, SAML, OIDC (
identity/) - REST control plane (
controlplane/) - Web-search skill plugin (
skills/web-search/)
- Chain-of-trust boot — Ed25519 signed kernel + dm-verity root hash
- Inference proxy — per-agent rate limiting, SQLite token tracking, JSONL audit log
- CEF syslog — SIEM-ready structured events from the eBPF monitor
- TLS termination — nginx with ACME/Let's Encrypt or self-signed
- Persistent master key — AES-256-GCM agent key storage survives restarts
- Structured logging —
log/slogJSON across all services
make build-go # Build all Go binaries (vm-launcher, cli, orchestrator, …)
make monitor # Build eBPF monitor (requires clang + libbpf)
make build-image # Build agent VM NixOS rootfs image
make sign # Sign kernel + rootfs with Ed25519 key (Phase 3)
make test-unit # Run Go unit tests
make test-phase3 # Run Phase 3 integration tests (requires live stack)
make go-mod-tidy # Run go mod tidy for all Go modules
make nix-hashes # Replace lib.fakeHash with real vendorHash values
make fmt # gofmt all Go codenix build .#clawos-cli
nix build .#vm-launcher
nix build .#clawos-orchestrator
nix build .#clawos-identity-manager
nix build .#clawos-control-plane
nix build .#inference-proxyAll services are configured via environment variables. Key variables:
| Variable | Service | Description |
|---|---|---|
CLAWOS_AGENT_KERNEL |
vm-launcher | Path to vmlinux kernel |
CLAWOS_AGENT_ROOTFS |
vm-launcher | Path to rootfs.img |
CLAWOS_AGENT_ROOTHASH |
vm-launcher | dm-verity root hash |
CLAWOS_SIGNING_PUBKEY |
vm-launcher | Hex Ed25519 public key |
CLAWOS_INFERENCE_PROXY_URL |
vm-launcher | Proxy URL injected into agent .env |
CLAWOS_MASTER_KEY |
identity | AES-256-GCM master key (hex, 64 chars) |
CLAWOS_MASTER_KEY_PATH |
identity | Path to persisted master key file |
CLAWOS_PROXY_ADDR |
inference-proxy | Listen address (default: 10.0.0.1:11435) |
CLAWOS_PROXY_RATE_LIMIT_RPM |
inference-proxy | Per-agent RPM limit (default: 60) |
ANTHROPIC_API_KEY |
agent .env | Anthropic API key (written to /workspace/.env) |
See each service's config.go or config.h for the full list.
# host.nix
services.clawos-inference-proxy-daemon = {
enable = true;
listenAddr = "10.0.0.1:11435";
rateLimitRPM = 60;
};
clawos.tls = {
enable = true;
domain = "clawos.example.com";
acmeEmail = "ops@example.com"; # omit for self-signed
};
clawos.verifiedBoot = {
enable = true;
enableSigning = true; # Phase 3 chain-of-trust
};clawos/
├── cli/ # clawos CLI (Go, cobra)
├── vm/ # vm-launcher daemon (Go)
│ ├── launcher.go # Firecracker lifecycle
│ ├── verify.go # Ed25519 image verification
│ └── store.go # VM state + PID file sync
├── orchestrator/ # Multi-agent orchestrator (Go)
├── identity/ # Identity manager — JWT + SAML/OIDC (Go)
├── controlplane/ # REST API gateway (Go)
├── inference-proxy/ # LLM API proxy (Go)
├── skills/
│ └── web-search/ # Web search skill plugin (Go)
├── observability/
│ └── monitor-daemon.c # eBPF monitor (C + libbpf)
├── scripts/
│ ├── build-agent-image.sh
│ ├── sign-agent-image.sh # Ed25519 chain-of-trust signing
│ ├── go-mod-tidy-all.sh
│ └── update-nix-hashes.sh
├── nix/
│ ├── hosts/
│ │ ├── host.nix # ClawOS host configuration
│ │ └── agent-vm.nix # Agent VM guest configuration
│ ├── modules/ # NixOS service modules
│ └── packages/ # Nix derivations
├── test/ # Integration tests
└── flake.nix
- Immutable rootfs — agent VM root filesystem is read-only, dm-verity protected. Any tampering fails the SHA-256 hash check at mount time.
- Signed images — kernel and root hash are Ed25519-signed. vm-launcher refuses to boot an unsigned or tampered image when signing is enabled.
- No virtiofs — workspace is an ext4 block device (
/dev/vdc), not a shared filesystem. No host path exposure. - eBPF audit trail — every syscall from every agent VM is recorded in JSONL and optionally forwarded to SIEM via CEF/syslog.
- JWT identity — each agent holds a short-lived Ed25519-signed JWT; the identity manager issues and rotates these. Agent keys are AES-256-GCM encrypted at rest.
- Rate-limited LLM access — agents cannot exceed their token budget; the inference proxy enforces per-agent RPM limits.
ClawOS targets NixOS as its primary build and deployment platform. For local development:
nix develop # enter the dev shell with all tools
make build-go # compile Go binaries
make test-unit # run fast unit tests (no KVM needed)PRs welcome. Please run make fmt before submitting.
MIT