Why nullclaw

• Lean by default: Zig compiles to a tiny static binary. No allocator overhead, no garbage collector, no runtime.
• Secure by design: pairing, strict sandboxing (landlock, firejail, bubblewrap, docker), explicit allowlists, workspace scoping, encrypted secrets.
• Fully swappable: core systems are vtable interfaces (providers, channels, tools, memory, tunnels, peripherals, observers, runtimes).
• No lock-in: OpenAI-compatible provider support + pluggable custom endpoints.

Benchmark Snapshot

Local machine benchmark (macOS arm64, Feb 2026), normalized for 0.8 GHz edge hardware.

Measured with /usr/bin/time -l on ReleaseSmall builds. nullclaw is a static binary with zero runtime dependencies.

Reproduce locally:

zig build -Doptimize=ReleaseSmall
ls -lh zig-out/bin/nullclaw

/usr/bin/time -l zig-out/bin/nullclaw --help
/usr/bin/time -l zig-out/bin/nullclaw status

Documentation

Start here if you want the shortest path to install, configure, operate, or extend nullclaw.

Localized documentation lives under docs/en/ and docs/zh/. Use the links below to jump straight to the page you need.

• Specialized guides: CONTRIBUTING.md, SECURITY.md, SIGNAL.md

Choose Your Path

After This README

• New here: jump to docs/en/README.md or docs/zh/README.md and follow the guided reading order.
• Want commands fast: open docs/en/commands.md or docs/zh/commands.md.
• Want to submit a PR: start with CONTRIBUTING.md, then read docs/en/development.md or docs/zh/development.md.

Quick Start

1) Recommended install (Homebrew)

The simplest path: install a ready-to-run binary with no extra runtime dependencies.

brew install nullclaw
nullclaw --help

2) Build from source

Prerequisite: use Zig 0.16.0 (exact version). Other Zig versions are currently unsupported and may fail to build. Verify before building: zig version should print 0.16.0. Debian users who need Zig first can follow docs/en/zig-installation.md.

git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig build -Doptimize=ReleaseSmall
zig build test --summary all

Make nullclaw available on PATH:

macOS/Linux (zsh/bash):

zig build -Doptimize=ReleaseSmall -p "$HOME/.local"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# or ~/.bashrc

Windows (PowerShell):

zig build -Doptimize=ReleaseSmall -p "$HOME\.local"

$bin = "$HOME\.local\bin"
$user_path = [Environment]::GetEnvironmentVariable("Path", "User")
if (-not ($user_path -split ";" | Where-Object { $_ -eq $bin })) {
  [Environment]::SetEnvironmentVariable("Path", "$user_path;$bin", "User")
}
$env:Path = "$env:Path;$bin"

Then:

nullclaw --help

3) Run with Docker Compose

The repository includes a Makefile wrapper around Docker Compose for local containerized runs.

make build
make config
make up

make config runs nullclaw onboard --interactive inside the agent container. Pass only non-secret flags through CONFIG_ARGS:

make config CONFIG_ARGS="--provider openrouter"

Avoid putting API keys or bot tokens in CONFIG_ARGS; command-line arguments can be exposed through shell history and process listings.

The compose gateway defaults to NULLCLAW_PORT=3210, binds inside the container on 0.0.0.0, and publishes to localhost on the host:

curl http://127.0.0.1:3210/health

Override the port or host bind address when needed:

make up NULLCLAW_PORT=8080
make up NULLCLAW_BIND=0.0.0.0

Operational shortcuts:

make logs
make down
make shell

Only set NULLCLAW_BIND=0.0.0.0 on trusted networks with pairing, webhook secrets, allowlists, and host firewall rules configured.

4) Common commands

# Quick setup
nullclaw onboard --api-key sk-... --provider openrouter

# Or interactive wizard
nullclaw onboard --interactive

# Chat
nullclaw agent -m "Hello, nullclaw!"

# Interactive mode
nullclaw agent

# Start gateway runtime (gateway + all configured channels/accounts + heartbeat + scheduler)
nullclaw gateway                # default: 127.0.0.1:3000
nullclaw gateway --port 8080    # custom port

# Check status
nullclaw status

# Run system diagnostics
nullclaw doctor

# Check channel health
nullclaw channel status

# Start specific channels
nullclaw channel start telegram
nullclaw channel start discord
nullclaw channel start signal

# Manage background service
# Linux supports systemd user services and OpenRC
nullclaw service install
nullclaw service status

# Optional secret injection hook for service mode:
# if ~/.nullclaw/service-env is executable, the installed service launcher runs it
# before starting `nullclaw gateway` (for example via dotenvx or sops)

# Migrate memory from OpenClaw
nullclaw migrate openclaw --dry-run
nullclaw migrate openclaw

Edge MVP (Hybrid Host + WASM Logic)

If you want edge deployment (Cloudflare Worker) with Telegram + OpenAI while keeping agent policy in WASM, see:

examples/edge/cloudflare-worker/

This pattern keeps networking/secrets in the edge host and lets you swap/update logic by replacing a tiny Zig WASM module.

Architecture

Every subsystem is a vtable interface — swap implementations with a config change, zero code changes.

Memory System

All custom, zero external dependencies for the core path:

{
  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "embedding_provider": "openai",
    "vector_weight": 0.7,
    "keyword_weight": 0.3,
    "hygiene_enabled": true,
    "snapshot_enabled": false
  }
}

Security

nullclaw enforces security at every layer.

Channel Allowlists

• Empty allowlist = deny all inbound messages
• "*" = allow all (explicit opt-in)
• Otherwise = exact-match allowlist

Nostr additionally: the owner_pubkey is always allowed regardless of dm_allowed_pubkeys. Private keys are encrypted at rest via SecretStore (enc2: prefix) and only decrypted into memory while the channel is running; zeroed on channel stop.

Nostr Channel Setup

nullclaw speaks Nostr natively via NIP-17 (gift-wrapped private DMs) and NIP-04 (legacy DMs), using nak.

Prerequisites: Install nak and ensure it's in your $PATH.

Setup via onboarding wizard:

nullclaw onboard --interactive   # Step 7 configures Nostr

The wizard will:

1. Generate a new keypair for your bot or import a key & encrypt it with ChaCha20-Poly1305
2. Ask for your (owner) pubkey (npub or hex) — always allowed through DM policy
3. Configure relays and DM relays (kind:10050 inbox)
4. Display the bot's pubkey

Or configure manually in the config.

How it works: On startup, nullclaw announces its DM inbox relays (kind:10050), then listens for incoming NIP-17 gift wraps and NIP-04 encrypted DMs. Outbound messages mirror the sender's protocol. Multi-relay rumor deduplication prevents duplicate responses when the same message is delivered via multiple relays.

Configuration

Config: ~/.nullclaw/config.json (created by onboard)

OpenClaw compatible: nullclaw uses the same config structure as OpenClaw (snake_case). Providers live under models.providers, the default model under agents.defaults.model.primary, and channels use accounts wrappers. Top-level default_provider / default_model keys are not supported.

Vertex AI note: models.providers.vertex.api_key supports either:

1. a bearer token (ya29...), or
2. a full Google service-account JSON object (same shape as Apps Script GEMINI_KEY with project_id, client_email, private_key).

models.providers.vertex.base_url can be set explicitly (.../projects/<id>/locations/<loc>/publishers/google/models), or omitted when service-account JSON is used (nullclaw will derive it from project_id, with VERTEX_LOCATION defaulting to global). Service-account mode requires openssl available in $PATH for RS256 JWT signing.

{
  "default_temperature": 0.7,

  "models": {
    "providers": {
      "openrouter": { "api_key": "sk-or-..." },
      "nearai": { "api_key": "YOUR_NEARAI_API_KEY" },
      "atlas-cloud": { "api_key": "YOUR_ATLASCLOUD_API_KEY" },
      "evolink": { "api_key": "YOUR_EVOLINK_API_KEY" },
      "groq": { "api_key": "gsk_..." },
      "vertex": {
        "api_key": {
          "type": "service_account",
          "project_id": "your-project",
          "client_email": "svc@your-project.iam.gserviceaccount.com",
          "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
        },
        "base_url": "https://aiplatform.googleapis.com/v1/projects/your-project/locations/global/publishers/google/models"
      },
      "anthropic": { "api_key": "sk-ant-...", "base_url": "https://api.anthropic.com" }
    }
  },

  "agents": {
    "defaults": {
      "model": { "primary": "openrouter/anthropic/claude-sonnet-4" },
      "heartbeat": { "every": "30m" }
    },
    "list": [
      { "id": "researcher", "model": { "primary": "openrouter/anthropic/claude-opus-4" }, "system_prompt": "..." }
    ]
  },

  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123:ABC",
          "allow_from": ["user1"],
          "reply_in_private": true,
          "proxy": "socks5://..."
        }
      }
    },
    "discord": {
      "accounts": {
        "main": {
          "token": "disc-token",
          "guild_id": "12345",
          "allow_from": ["user1"],
          "allow_bots": false
        }
      }
    },
    "irc": {
      "accounts": {
        "main": {
          "host": "irc.libera.chat",
          "port": 6697,
          "nick": "nullclaw",
          "channel": "#nullclaw",
          "tls": true,
          "allow_from": ["user1"]
        },
        "meshrelay": {
          "host": "irc.meshrelay.xyz",
          "port": 6697,
          "nick": "nullclaw",
          "channels": ["#agents"],
          "tls": true,
          "nickserv_password": "YOUR_NICKSERV_PASSWORD",
          "allow_from": ["*"]
        }
      }
    },
    "slack": {
      "accounts": {
        "main": {
          "bot_token": "xoxb-...",
          "app_token": "xapp-...",
          "allow_from": ["user1"]
        }
      }
    },
    "nostr": {
      "private_key": "enc2:...",
      "owner_pubkey": "hex-pubkey-of-owner",
      "relays": ["wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"],
      "dm_allowed_pubkeys": ["*"],
      "display_name": "NullClaw",
      "about": "AI assistant on Nostr",
      "nip05": "nullclaw@yourdomain.com",
      "lnurl": "lnurl1..."
    }
  },

  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "language": "ru",
        "models": [{ "provider": "groq", "model": "whisper-large-v3" }]
      }
    }
  },

  "mcp_servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "remote": {
      "transport": "http",
      "url": "https://mcp.example.com/rpc",
      "timeout_ms": 10000,
      "headers": {
        "Authorization": "Bearer example-token"
      }
    }
  },

  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "embedding_provider": "openai",
    "vector_weight": 0.7,
    "keyword_weight": 0.3
  },

  "gateway": {
    "port": 3000,
    "require_pairing": true,
    "allow_public_bind": false
  },

  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20
  },

  "runtime": {
    "kind": "native",
    "docker": {
      "image": "alpine:3.20",
      "network": "none",
      "memory_limit_mb": 512,
      "read_only_rootfs": true
    }
  },

  "tunnel": { "provider": "none" },
  "secrets": { "encrypt": true },
  "identity": { "format": "openclaw" },

  "security": {
    "sandbox": { "backend": "auto" },
    "resources": { "max_memory_mb": 512, "max_cpu_percent": 80 },
    "audit": { "enabled": true, "retention_days": 90 }
  }
}

Config values are literal. NullClaw does not expand ${VAR} inside config.json strings, including custom header values. If you need environment-based secrets, render config.json ahead of time with your own deployment tooling.

Telegram forum topics:

• Topic session isolation is automatic. You do not add a topic_id field under channels.telegram.
• The easiest operator flow is:
  1. define named agent profiles under agents.list
  2. open the target Telegram chat or forum topic
  3. run /bind <agent>
• To bind a specific Telegram forum topic to a specific agent, use bindings[].match.peer.id with the canonical thread form "<chat_id>:thread:<topic_id>".
• To bind the whole Telegram group as a fallback for all other topics, keep a normal group binding with "<chat_id>".
• /bind status shows the current effective route and the available agent ids.
• /bind clear removes only the exact binding for the current account/chat/topic and falls back to the broader route.
• /bind persists an exact bindings[] entry for the current Telegram account and peer.
• /bind status distinguishes an exact local override from an inherited broader fallback.
• Topic-specific bindings win over group fallback by route priority; the order in bindings[] does not matter.
• Telegram menu visibility for /bind is controlled by channels.telegram.accounts.<id>.binding_commands_enabled.

Example:

{
  "bindings": [
    {
      "agent_id": "coder",
      "match": {
        "channel": "telegram",
        "account_id": "main",
        "peer": { "kind": "group", "id": "-1001234567890:thread:42" }
      }
    },
    {
      "agent_id": "orchestrator",
      "match": {
        "channel": "telegram",
        "account_id": "main",
        "peer": { "kind": "group", "id": "-1001234567890" }
      }
    }
  ]
}

In that setup, topic 42 routes to coder, while the rest of the forum falls back to orchestrator.

Named agent profiles are configured separately from bindings. Bindings only choose which named agent handles a given chat/topic.

If a named agent should run from its own workspace, set agents.list[].workspace_path. Relative paths are resolved from the directory that contains config.json, the workspace is scaffolded on first use, and the agent gets a durable memory namespace agent:<agent-id>. Setting workspace_path does not disable system_prompt: when both are configured, the named profile prompt is still applied and the workspace bootstrap files are loaded from that dedicated workspace. This applies to nullclaw agent --agent <id>, /subagents spawn --agent <id>, and routed sessions resolved through bindings.

Minimal end-to-end example:

{
  "agents": {
    "list": [
      {
        "id": "orchestrator",
        "provider": "openrouter",
        "model": "anthropic/claude-sonnet-4"
      },
      {
        "id": "coder",
        "provider": "ollama",
        "model": "qwen2.5-coder:14b",
        "system_prompt": "You are the coding agent for this topic."
      }
    ]
  },
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123456:ABCDEF",
          "allow_from": ["YOUR_TELEGRAM_USER_ID"],
          "binding_commands_enabled": true,
          "topic_commands_enabled": true,
          "topic_map_command_enabled": true,
          "commands_menu_mode": "scoped"
        }
      }
    }
  },
  "bindings": [
    {
      "agent_id": "orchestrator",
      "match": {
        "channel": "telegram",
        "account_id": "main",
        "peer": { "kind": "group", "id": "-1001234567890" }
      }
    }
  ]
}

Operator flow:

• Send /bind coder inside the target forum topic.
• nullclaw writes a new exact bindings[] entry to ~/.nullclaw/config.json for that topic and Telegram account.
• The next message in that topic uses the new routed agent profile.
• nullclaw must have write access to ~/.nullclaw/config.json for /bind to persist changes.

About account_id:

• account_id identifies the configured Telegram account entry, not a topic and not an agent.
• In the usual channels.telegram.accounts form, the object key becomes the account id. For example, accounts.main means account_id = "main", and accounts.backup means account_id = "backup".
• In bindings, match.account_id limits that binding to one specific Telegram account.
• If match.account_id is omitted, the binding can match any Telegram account for that channel.
• Use different account ids only when you run multiple Telegram bot accounts/tokens in the same nullclaw instance.

Effect on delivery:

• Incoming Telegram updates are processed by the account that received them.
• Routing uses that same account_id, so match.account_id = "main" matches only messages received by channels.telegram.accounts.main.
• Replies go back out through the same Telegram account/runtime that handled the message.
• Setting one binding to account_id = "main" and another to account_id = "sub" does not split one chat across two agents automatically; it scopes each binding to a different configured Telegram account.

Full Web Search + Shell Access

Use this when you want full web-search provider control plus unrestricted shell command allowlist behavior:

{
  "http_request": {
    "enabled": true,
    "search_base_url": "https://searx.example.com",
    "search_provider": "auto",
    "search_fallback_providers": ["jina", "duckduckgo"]
  },
  "autonomy": {
    "level": "full",
    "allowed_commands": ["*"],
    "allowed_paths": ["*"],
    "require_approval_for_medium_risk": false,
    "block_medium_risk_commands": false,
    "block_high_risk_commands": false
  }
}

• http_request.search_base_url accepts either instance root (https://host) or explicit endpoint (https://host/search); local/private SearXNG instances may also use plain HTTP such as http://localhost:8888 or http://192.168.1.10:8888/search.
• Invalid http_request.search_base_url now fails config validation at startup (no automatic fallback for malformed URL).
• http_request.search_provider supports: auto, searxng, duckduckgo (ddg), brave, firecrawl, tavily, perplexity, exa, jina.
• http_request.search_fallback_providers is optional and is tried in order when the primary provider fails.
• Provider env vars: BRAVE_API_KEY, FIRECRAWL_API_KEY, TAVILY_API_KEY, PERPLEXITY_API_KEY, EXA_API_KEY, JINA_API_KEY (or shared WEB_SEARCH_API_KEY where supported). DuckDuckGo and SearXNG do not require API keys.
• allowed_commands entries support "cmd", "cmd *", and "*" formats.
  • "cmd" and "cmd *" both allow that command family at the allowlist stage.
  • "*" allows any command at the allowlist stage.
• High-risk and medium-risk runtime gates still apply after the allowlist check; set block_medium_risk_commands: false when you intentionally allow network/transfer commands such as curl/wget or other medium-risk mutations.
• allowed_paths: ["*"] allows access outside workspace, except system-protected paths.

Web UI / Browser Relay

Use channels.web for browser UI events (WebChannel v1):

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "local",
          "listen": "127.0.0.1",
          "port": 32123,
          "path": "/ws",
          "auth_token": "replace-with-long-random-token",
          "message_auth_mode": "pairing",
          "allowed_origins": ["http://localhost:5173", "chrome-extension://your-extension-id"]
        }
      }
    }
  }
}

• Local: keep "listen": "127.0.0.1".
• message_auth_mode controls inbound user_message auth:
  • "pairing" (default): send pairing_request, receive pairing_result, include UI access_token in every user_message.
  • "token" (local transport only): include auth_token in each user_message payload (access_token is also accepted for compatibility).
• auth_token hardens the WebSocket upgrade and becomes required when binding non-loopback addresses.
• Unauthenticated WebSocket upgrade is loopback-only. Pairing-first local UX works on 127.0.0.1, but a public/LAN bind must authenticate the /ws upgrade on the first hop with ?token=<auth_token> or Authorization: Bearer <auth_token>.
• Local loopback pairing no longer depends on a fixed shared code. pairing_request may omit payload.pairing_code, and legacy loopback clients that still send 123456 remain compatible.
• /ws is the WebSocket endpoint. /pair belongs to the HTTP gateway API and is not part of the web channel handshake.
• Remote/headless host: if you bind "listen": "0.0.0.0", prefer a stable configured token plus message_auth_mode: "token" behind TLS/reverse proxy, or keep loopback bind and expose it through SSH tunnel/proxy.
• UI/extension should live in a separate repository and connect via this WebSocket endpoint.
• For orchestration, use local token mode with a stable token from config or env (NULLCLAW_WEB_TOKEN, NULLCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_TOKEN).
• Relay transport (outbound agent socket) is configured via:

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "relay",
          "relay_url": "wss://relay.nullclaw.io/ws/agent",
          "relay_agent_id": "default",
          "relay_token": "replace-with-relay-token",
          "relay_token_ttl_secs": 2592000,
          "relay_pairing_code_ttl_secs": 300,
          "relay_ui_token_ttl_secs": 86400,
          "relay_e2e_required": false
        }
      }
    }
  }
}

• Relay token lifecycle (dedicated): relay_token (config) -> NULLCLAW_RELAY_TOKEN (env) -> persisted web-relay-<account_id> credential -> generated token.
• Relay UI handshake: send pairing_request with one-time pairing_code, receive pairing_result with UI access_token JWT (and optional set_cookie string for relay HTTP layer).
• Relay user_message must include valid UI JWT in access_token (top-level or payload.access_token).
• If E2E is enabled (relay_e2e_required=true), UI and agent exchange X25519 keys during pairing and send encrypted payloads in payload.e2e.
• WebChannel event envelope is defined in spec/webchannel_v1.json.

Gateway API

A2A (Agent-to-Agent Protocol v0.3.0)

NullClaw implements Google's A2A protocol v0.3.0, allowing any A2A-compatible agent or client to discover, authenticate, and interact with your instance over JSON-RPC 2.0.

Enable in ~/.nullclaw/config.json:

{
  "a2a": {
    "enabled": true,
    "name": "nullclaw",
    "description": "General-purpose AI assistant",
    "url": "https://example.com",
    "version": "1.0.0"
  }
}

Endpoints:

Supported methods: message/send, message/stream, tasks/get, tasks/cancel, tasks/list, tasks/resubscribe.

Quick test:

# 1. Get a bearer token
# Set PAIRING_CODE to the one-time code for this gateway session.
TOKEN=$(curl -s -X POST -H "X-Pairing-Code: $PAIRING_CODE" http://localhost:3000/pair | jq -r .token)

# 2. Discover the agent
curl http://localhost:3000/.well-known/agent-card.json

# 3. Send a message
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"messageId":"msg-1","role":"user","parts":[{"kind":"text","text":"Hello"}]}}}' \
  http://localhost:3000/a2a

See Gateway API docs for full A2A reference including streaming, task lifecycle, and configuration details.

Media transcription

POST /media/transcribe accepts JSON with audio_base64, mime_type, source, and optional language, then returns {"text":"..."} plus metadata. Configure STT under tools.media.audio; remote custom STT endpoints must use HTTPS. Raise gateway.max_body_size_bytes, gateway.request_timeout_secs, and gateway.webhook_rate_limit_per_minute for live desktop audio chunking.

Commands

Development

Build and tests are pinned to Zig 0.16.0.

zig build                          # Dev build
zig build -Doptimize=ReleaseSmall  # Release build (678 KB)
zig build test --summary all       # 5,300+ tests

Channel Flow Coverage

Channel CJM coverage (ingress parsing/filtering, session key routing, account propagation, bus handoff) is validated by tests in:

• src/channel_manager.zig (runtime channel registration/start semantics + listener mode wiring)
• src/config.zig (OpenClaw-compatible channels.*.accounts parsing, multi-account selection/ordering, aliases)
• src/gateway.zig (Telegram/WhatsApp/LINE/Lark routed session keys from webhook payloads)
• src/daemon.zig (gateway-loop inbound route resolution for Discord/QQ/OneBot/Mattermost/MaixCam)
• src/channels/discord.zig, src/channels/mattermost.zig, src/channels/qq.zig, src/channels/onebot.zig, src/channels/signal.zig, src/channels/line.zig, src/channels/whatsapp.zig (per-channel inbound/outbound contracts)

Project Stats

Language:     Zig 0.16.0
Source files: ~250
Lines of code: ~249,000
Tests:        5,300+
Binary:       678 KB (ReleaseSmall)
Peak RSS:     ~1 MB
Startup:      <2 ms (Apple Silicon)
Dependencies: 0 (besides libc + optional SQLite)

Source Layout

src/
  main.zig              CLI entry point + argument parsing
  root.zig              Module hierarchy (public API)
  config.zig            JSON config loader + 30 sub-config structs
  agent.zig             Agent loop, auto-compaction, tool dispatch
  daemon.zig            Daemon supervisor with exponential backoff
  gateway.zig           HTTP gateway (rate limiting, idempotency, pairing)
  channels/             19 channel implementations (telegram, signal, discord, slack, nostr, matrix, whatsapp, line, lark, onebot, mattermost, qq, ...)
  providers/            50+ AI provider integrations
  memory/               SQLite backend, embeddings, vector search, hygiene, snapshots
  tools/                35+ tool implementations
  security/             Secrets (ChaCha20), sandbox backends (landlock, firejail, ...)
  cron.zig              Cron scheduler with JSON persistence
  health.zig            Component health registry
  tunnel.zig            Tunnel vtable (cloudflare, ngrok, tailscale, custom)
  peripherals.zig       Hardware peripheral vtable (serial, Arduino, RPi, Nucleo)
  runtime.zig           Runtime vtable (native, docker, WASM)
  skillforge.zig        Skill discovery (GitHub), evaluation, integration
  ...

Versioning

nullclaw uses CalVer (YYYY.M.D) for releases — e.g. v2026.2.20.

• Tag format: vYYYY.M.D (one release per day max; patch suffix vYYYY.M.D.N if needed)
• Release binaries derive their embedded version from the git tag (v... -> nullclaw --version)
• Non-release builds default to dev unless you override with zig build -Dversion=...
• No stability guarantees yet — the project is pre-1.0, config and CLI may change between releases
• nullclaw --version prints the current version

Contributing

See CONTRIBUTING.md for development environment setup, workflow, validation commands, and the PR checklist.

Implement a vtable interface, submit a PR:

• New Provider -> src/providers/
• New Channel -> src/channels/
• New Tool -> src/tools/
• New Memory backend -> src/memory/
• New Tunnel -> src/tunnel.zig
• New Sandbox backend -> src/security/
• New Peripheral -> src/peripherals.zig
• New Skill -> ~/.nullclaw/workspace/skills/<name>/ or ~/.nullclaw/workspace/skills/<category>/<name>/

Chinese Docs (中文文档)

• Chinese docs overview (中文文档总览)
• Installation guide (安装指南)
• Zig installation (Zig 安装指南)
• Configuration guide (配置指南)
• Usage and operations (使用与运维)
• Architecture overview (架构总览)
• Security model (安全机制)
• Gateway API (中文)
• Commands reference (命令参考)
• Development guide (开发指南)

English Docs

• English docs overview
• Installation
• Zig Installation
• Configuration
• Usage and operations
• Architecture
• Security
• Gateway API
• Commands
• Development

Disclaimer

nullclaw is a pure open-source software project. It has no token, no cryptocurrency, no blockchain component, and no financial instrument of any kind. This project is not affiliated with any token or financial product.

License

MIT — see LICENSE

nullclaw — Null overhead. Null compromise. Deploy anywhere. Swap anything.

Star History