Skip to content

Kodachi Claw - Anonymous AI Agent Runtime

Documentation Navigation

Navigate the documentation:

File Information

Property Value
Binary Name kodachi-claw
Version 9.0.1
File Size 28.5MB
Author theonlyhennygod
License Proprietary - Kodachi OS
Category AI & Intelligence
Description Kodachi hardened AI runtime with embedded anonymity controls
JSON Data View Raw JSON

SHA256 Checksum

4fa8049ed9b757466d9431151232b94436a2382cde7fce122373c90143335242

The Power of ZeroClaw. The Anonymity of Kodachi.

Get the power of ZeroClaw with full anonymity. Forged from ZeroClaw's ultra-lightweight Rust agent engine, kodachi-claw hides your AI agent inside the Tor network. Every API call, every model request, every channel message is routed through embedded Tor circuits. Your agent cannot be tracked, fingerprinted, or traced back to you.

While other AI agent runtimes run on the open internet, kodachi-claw wraps that same agent runtime with Kodachi's anonymity stack: embedded Tor circuits, identity randomization, OPSEC filtering, and network namespace isolation.

What is ZeroClaw?

ZeroClaw is an ultra-lightweight Rust AI agent runtime, the fastest and smallest autonomous assistant. kodachi-claw extends that foundation with backend-verified capabilities including 12+ AI providers, 14 communication channels, embedded Tor anonymity, and secure scheduling/tool execution from a single static binary.

kodachi-claw is forged from ZeroClaw and inspired by OpenClaw, the original Node.js personal AI assistant that pioneered multi-channel agent communication. kodachi-claw takes the ZeroClaw engine and wraps it with Kodachi's anonymity stack, making it the only AI agent runtime that operates entirely inside the Tor network.

Independent Runtime

kodachi-claw is not a KAICS sub-binary. It is an independent, standalone runtime that integrates Kodachi services (online-auth, ip-fetch, tor-switch, oniux) directly as in-process Rust libraries.

Scenario-First Documentation

This page is intentionally focused on operational scenarios and step-by-step flows. For the full command and flag catalog, use the kodachi-claw CLI Reference.

The Claw Family

Claw Family Variants 7 PROJECTS

All variants of the open-source AI agent runtime family, from the original Node.js project to ultra-minimal Zig and anonymity-hardened Kodachi fork.

Project Language Size Description Repository
OpenClaw Node.js ~28MB dist · >1GB RAM The original personal AI assistant on any platform openclaw/openclaw
ZeroClaw Rust 3.4MB bin · <5MB RAM Ultra-lightweight: 99% less memory, runs on $10 hardware zeroclaw-labs/zeroclaw
NullClaw Zig 678KB bin · ~1MB RAM Fastest and smallest: 678KB binary, <2ms startup nullclaw/nullclaw
PicoClaw Go ~8MB bin · <10MB RAM Tiny personal agent: <10MB RAM footprint sipeed/picoclaw
IronClaw Rust ~4MB bin · <8MB RAM Privacy-focused with WASM-sandboxed tools nearai/ironclaw
NanoClaw TypeScript ~12MB dist · ~80MB RAM Lightweight container-secured agent with Claude Agent SDK, WhatsApp, scheduled jobs qwibitai/nanoclaw
Kodachi Claw Rust 28.3MB bin · ~45MB RAM Anonymity-hardened: embedded Tor, OPSEC filter, namespace isolation Desktop XFCE · Terminal Server · Binary Package · Standalone Download · CLI Reference

Key Differentiator

All the claws give you an AI agent. Only kodachi-claw makes that agent invisible.

Standalone Download

kodachi-claw ships pre-installed with the Kodachi Terminal Server ISO, the Kodachi Desktop XFCE ISO, and the binary package. For separate deployment, it is also available as a standalone download below — no installer needed. You can download the binary and signature separately, or download both in one compressed file (kodachi-claw.zip). The public key is embedded at compile time, so only the binary and its .sig file are required.

kodachi-claw Binary

Standalone

Single static binary with embedded Tor runtime, identity randomization, and OPSEC filtering. Linux x86-64 only. Use the compressed zip download to get both required files in one package.

v9.0.1 28.5MB

Installation

Runtime Signature Notice

Make the binary executable and keep the signature available either in the same folder as kodachi-claw or at results/signatures/ relative to the binary path. You can also download kodachi-claw.zip and extract it. No dependencies required; everything is statically linked.

# Option 0: single compressed download (binary + signature)
mkdir -p ~/kodachi-claw && cd ~/kodachi-claw
wget https://www.kodachi.cloud/apps/os/install/kodachi-claw/kodachi-claw.zip
unzip -o kodachi-claw.zip
chmod 755 kodachi-claw

# Option 0b: single compressed download with curl (same result)
mkdir -p ~/kodachi-claw && cd ~/kodachi-claw
curl -LO https://www.kodachi.cloud/apps/os/install/kodachi-claw/kodachi-claw.zip
unzip -o kodachi-claw.zip
chmod 755 kodachi-claw

# Option 1: wget (download both files to a new folder)
mkdir -p ~/kodachi-claw && cd ~/kodachi-claw
wget https://www.kodachi.cloud/apps/os/install/kodachi-claw/kodachi-claw
wget https://www.kodachi.cloud/apps/os/install/kodachi-claw/kodachi-claw_v9.0.1.sig
chmod 755 kodachi-claw

# Option 2: curl (same result, different tool)
mkdir -p ~/kodachi-claw && cd ~/kodachi-claw
curl -LO https://www.kodachi.cloud/apps/os/install/kodachi-claw/kodachi-claw
curl -LO https://www.kodachi.cloud/apps/os/install/kodachi-claw/kodachi-claw_v9.0.1.sig
chmod 755 kodachi-claw

# Run (requires sudo for identity randomization)
sudo ./kodachi-claw onboard --interactive

Both Files Required

You must have both kodachi-claw (the binary) and kodachi-claw_v9.0.1.sig (the signature). The signature can be placed either in the same folder as the binary or in results/signatures/ relative to the binary path. Without the .sig file in one of those locations, kodachi-claw will refuse to run. If you download kodachi-claw.zip, extract it first. You can use any directory you like: ~/Desktop, ~/Downloads, /opt/kodachi-claw, or anywhere else.

Binary Integrity & Build Info
Version
9.0.1
Build Date
2026-02-26
File Size
28.5MB
SHA256 Checksum:
4fa8049ed9b757466d9431151232b94436a2382cde7fce122373c90143335242

Verification: The public key is embedded at compile time. Place the .sig file either in the same directory as the binary or in results/signatures/ relative to it — kodachi-claw verifies its own signature on startup.

ZeroClaw vs Kodachi Claw

kodachi-claw shares the ZeroClaw agent engine but adds a full anonymity stack, enhanced security, Kodachi service integration, and CLI enhancements. This table shows what kodachi-claw adds on top of ZeroClaw:

ZeroClaw Base Engine UPSTREAM

The open-source Rust agent runtime that Kodachi Claw is forked from. All features below are inherited.

Category Feature
AI Providers OpenAI, Anthropic (Claude), OpenRouter, Groq, Ollama, and custom OpenAI-compatible endpoints. Current backend reports 12+ primary providers, plus additional gateway provider profiles.
Channels 14 communication channels in current backend (including Telegram, Discord, Slack, Matrix) with multi-channel daemon runtime.
Tools Shell execution, file operations, memory management, cron scheduling, Git integration, HTTP requests, browser automation, screenshots, image analysis, Composio integrations, delegation
Memory Backends: SQLite (default), PostgreSQL, Markdown files, Lucid. Hybrid vector + keyword search (FTS5 BM25). Auto-save, LRU cache, snapshot/hydrate, safe reindex.
Hardware STM32 microcontrollers, Raspberry Pi GPIO, USB peripherals. Runs on ARM64, x86-64, ARMv7. Optimized for <5MB RAM on $10 hardware.
Security Gateway pairing, Docker sandboxing, allowlists, rate limiting, filesystem scoping, encrypted secrets at rest, workspace isolation, config-based access control
Secret Store ChaCha20-Poly1305 AEAD encrypted credential storage with multi-profile authentication
Integrations 50+ integrations exposed via the integrations browser, plus skill loader support for custom capability packs.
Tunneling Cloudflare, Tailscale, ngrok, custom implementations, or none
Observability Noop, Log, Multi observer types. Extensible for Prometheus and OpenTelemetry.
Scheduler Cron-based task scheduling, heartbeat engine for periodic tasks, persistent job store
Daemon Mode Systemd service management, background operation, auto-restart, one-click bootstrap installer
Runtime Native execution, Docker sandboxed runtime. Response caching, memory migration from competing systems, shell completions, diagnostics.

What Kodachi Claw Adds KODACHI EXCLUSIVE

Production-grade anonymity layer built on top of ZeroClaw. These features exist only in Kodachi Claw.

Addition What It Does
Embedded Arti Tor Full Tor stack compiled into the binary. Multi-circuit pool (default 10 instances) with load balancing. Every API call, model request, and channel message routed through Tor.
Circuit Pool Manager Configurable circuit count (1-50), sticky circuits for session consistency, automatic circuit rotation, health monitoring per circuit.
Identity Randomization MAC address randomization via macchanger, hostname randomization via hostnamectl, timezone randomization via timedatectl. All on startup, auto-restored on exit.
OPSEC Filter Scans all outbound agent messages and redacts identity leaks (real IPs, hostnames, usernames, MAC addresses) before they reach any provider or channel.
Namespace Isolation (oniux) Kernel-level network namespace via oniux. All traffic is forced through Tor at the OS level. No DNS or IP leaks possible, even from child processes.
IP Leak Verification Automated check on startup via ip-fetch. Confirms traffic exits through Tor network, not your real IP. Blocks operation if verification fails.
DNS Leak Verification Automated DNS leak test on startup. Confirms DNS queries are routed through Tor, not your ISP resolvers.
Kodachi Auth Gate In-process online-auth integration with device ID verification, auto-recovery, and session persistence. No external auth binary needed.
Extended Sandboxing Adds Bubblewrap and Firejail backends on top of ZeroClaw's Landlock and Docker support.
Preflight Checks Full anonymity preflight before agent starts: Tor bootstrap, identity randomization, IP/DNS verification, OPSEC filter init, instance locking.
Cleanup on Exit Restores original MAC, hostname, and timezone on exit. Tears down Tor circuits and cleans instance locks.
4 Circuit Strategies Round-robin, random, least-used, and sticky strategies for Tor circuit selection. Sticky keeps the same exit node per channel to prevent identity flickering.
Instance Locking Prevents Tor instance conflicts across concurrent runs. Ensures only one kodachi-claw process controls the circuit pool at a time.
Claude Code CLI Provider No API key needed — invokes installed Claude Code CLI directly as a subprocess. Lazy path detection, 120s timeout, secret scrubbing.
ai-gateway Integration Safe command execution through policy firewall and approval workflow. Three-tier risk classification with human-in-the-loop for dangerous operations.
CLI Enhancements (cli-core) --json / --json-pretty / --json-human output modes, -e examples, -n info. Consistent CLI framework shared across all Kodachi binaries.
Internet Recovery Automatic connectivity check (IP ping + DNS resolve) after identity changes and on shutdown. Invokes health-control NetworkRecovery in-process when connectivity is lost. Standalone recover-internet subcommand for on-demand recovery.
Signal Handler Graceful SIGINT/SIGTERM handling ensures cleanup (identity restore, internet recovery, Tor teardown) always runs, even when interrupted with Ctrl+C.
Service Libraries Integrates online-auth, ip-fetch, tor-switch, oniux, dns-leak, permission-guard, integrity-check, deps-checker, logs-hook, health-control as in-process Rust libraries (not shell calls).

Anonymity Architecture

kodachi-claw wraps the ZeroClaw agent engine with a multi-layered anonymity stack:

┌─────────────────────────────────────────────────────────────┐
│                     kodachi-claw binary                      │
│                                                              │
│  ┌──────────┐   ┌────────────────────────────────────────┐  │
│  │  Agent    │   │     Anonymity Stack                    │  │
│  │  Engine   │   │                                        │  │
│  │ ─────────→│   │  ┌──────────┐  ┌───────────────────┐  │  │
│  │ Providers │   │  │ OPSEC    │  │ Identity           │  │  │
│  │ Channels  │   │  │ Filter   │  │ Randomization      │  │  │
│  │ Tools     │   │  │ (redact) │  │ MAC/Host/Timezone  │  │  │
│  │ Memory    │   │  └────┬─────┘  └───────────────────┘  │  │
│  │ Scheduler │   │       │                                │  │
│  └──────────┘   │  ┌────▼───────────────────────────────┐│  │
│                  │  │    Embedded Arti Tor Runtime        ││  │
│                  │  │    ┌─────┐┌─────┐┌─────┐ ... ×10   ││  │
│                  │  │    │Circ1││Circ2││Circ3│            ││  │
│                  │  │    └──┬──┘└──┬──┘└──┬──┘            ││  │
│                  │  └───────┼──────┼──────┼───────────────┘│  │
│                  └──────────┼──────┼──────┼────────────────┘  │
└─────────────────────────────┼──────┼──────┼──────────────────┘
                              ▼      ▼      ▼
                         Tor Exit Nodes → AI Providers / Channels

Embedded Tor Runtime

kodachi-claw embeds the Arti Tor stack directly into the binary, no external Tor daemon needed.

Mode Flag Description
Multi-Circuit (default) --mode multi-circuit Pool of N Tor instances (default 10), load-balanced across requests
Isolated --mode isolated Full network namespace via oniux, separate kernel network stack
Single --mode single One Tor circuit for low-resource environments

Circuit assignment strategies (--circuit-strategy):

Strategy Behavior
round-robin (default) Each request goes to the next circuit in sequence
random Random circuit per request
least-used Route to the circuit with fewest active connections
sticky Same tool/channel always uses the same circuit

Identity Randomization

On startup, kodachi-claw randomizes your system fingerprint:

Feature Flag to Skip Description
MAC address --skip-mac Randomizes network interface MAC address
Hostname --skip-hostname Sets a random hostname
Timezone --skip-timezone Sets a random timezone
All three --skip-identity Skip all identity randomization

Use --restore-on-exit to restore original MAC, hostname, and timezone on shutdown.

Use --auto-recover-internet to automatically check and recover internet connectivity after each identity change (especially MAC randomization which cycles network interfaces) and on shutdown.

Verification & Leak Prevention

Feature Flag to Skip Description
IP verification --skip-ip-check Confirms traffic exits through Tor
DNS verification --skip-dns-check Confirms DNS queries don't leak
OPSEC filter - Redacts outbound identity leaks from agent messages
Auth gate --auth-mode auto\|required Kodachi online-auth integration (always runs, mode controls failure behavior)
Preflight checks --skip-integrity-check, --skip-permission-check Integrity and permission verification before launch

Tor Instance Management

Setting Flag Default
Pool size --tor-instances N 10
Instance policy --instance-policy reuse (alternatives: new, mixed)
Instance prefix --instance-prefix kodachi-claw-instance

Namespace Isolation (oniux)

With --mode isolated, kodachi-claw uses oniux to create a Linux network namespace that forces ALL traffic through Tor at kernel level, no bypass is possible, even from misbehaving tools or libraries.

Quick Start

First-Time Setup

# 1. Run the interactive setup wizard
kodachi-claw onboard --interactive

# 2. Quick setup with an API key (user context)
kodachi-claw onboard --api-key sk-... --provider openrouter

# 3. If you will run agent/daemon with sudo, onboard in sudo context too
sudo kodachi-claw onboard --api-key sk-... --provider openrouter
sudo chmod 600 /root/.kodachi-claw/config.toml

Why kodachi-claw Usually Runs With sudo

kodachi-claw performs OS-level anonymity operations that require elevated privileges: - MAC randomization (macchanger) - Hostname changes (hostnamectl/hostname) - Timezone changes (timedatectl) - Tor runtime/network setup and instance management - Namespace isolation in --mode isolated (root or CAP_NET_ADMIN)

Sudo vs non-sudo behavior (validated on 2026-02-23)

Run context Command Verified result What it means
Non-sudo shell (user) kodachi-claw --json-pretty status --skip-all config_path: /home/<user>/.kodachi-claw/config.toml Uses user config only.
Sudo shell (root) sudo kodachi-claw --json-pretty status --skip-all config_path: /root/.kodachi-claw/config.toml Uses root config only.
Feature capability check kodachi-claw -n --json-pretty Root/sudo required for MAC/hostname/timezone randomization Full identity randomization needs elevated privileges.

Rule: if you run agent or daemon with sudo, also run onboard with sudo so the key is saved to /root/.kodachi-claw/config.toml.

API Keys With sudo: Important

Plain sudo does not keep your exported user API keys. This is why keys set only in user shell env may not be visible to root-run sessions.

# Preferred for sudo runtime: pass key via variable and let onboard build full config
read -rsp 'Enter API key: ' API_KEY; echo
sudo kodachi-claw onboard --api-key "$API_KEY" --provider openrouter
sudo chmod 600 /root/.kodachi-claw/config.toml
unset API_KEY

# Non-interactive variant (CI/scripts)
API_KEY='sk-or-v1-REPLACE_ME'
sudo kodachi-claw onboard --api-key "$API_KEY" --provider openrouter
sudo chmod 600 /root/.kodachi-claw/config.toml
unset API_KEY

# Session-only alternative: preserve env vars for one command (does not rewrite config)
export OPENROUTER_API_KEY="sk-or-v1-REPLACE_ME"
sudo -E kodachi-claw agent --message "hello"

Do Not Hand-Write Minimal config.toml

Do not create /root/.kodachi-claw/config.toml with only api_key = "...". kodachi-claw requires additional fields (for example default_temperature), and a minimal file will fail to parse. Also note: onboard may create this file with mode 644 depending on system umask; set mode 600 after sudo onboarding.

# Repair root config if an old command wrote a minimal/incomplete file
sudo mv /root/.kodachi-claw/config.toml /root/.kodachi-claw/config.toml.bak.$(date +%s) 2>/dev/null || true
read -rsp 'Enter API key: ' API_KEY; echo
sudo kodachi-claw onboard --api-key "$API_KEY" --provider openrouter
sudo chmod 600 /root/.kodachi-claw/config.toml
unset API_KEY

Launch Anonymous Agent

# Start interactive agent with full anonymity (10 Tor circuits)
sudo kodachi-claw agent

# Single query through Tor
sudo kodachi-claw agent --message "check my security posture"

# Start autonomous daemon (all channels + gateway + scheduler)
sudo kodachi-claw daemon

Control Anonymity Level

# Maximum isolation — kernel-level namespace via oniux
sudo kodachi-claw --mode isolated agent

# 20 Tor circuits for high-throughput agents
sudo kodachi-claw --tor-instances 20 daemon

# Sticky circuits — same tool always uses same exit node
sudo kodachi-claw --circuit-strategy sticky daemon

# Restore identity on exit
sudo kodachi-claw --restore-on-exit agent

# Skip all anonymity (direct connection — local testing only)
sudo kodachi-claw --skip-anonymity agent

Check Status

# Show Tor circuits, identity state, agent status
sudo kodachi-claw status

# JSON output for automation
sudo kodachi-claw --json-pretty status

# Show built-in command help/examples (full catalog is in CLI Reference page)
kodachi-claw -e

Kodachi Service Integration

kodachi-claw integrates these Kodachi services directly as in-process Rust libraries (not external binary calls):

Service Integration
online-auth Authentication gate, verifies Kodachi license before agent launch
ip-fetch IP verification, confirms traffic exits through Tor
tor-switch Tor instance management, creates and manages embedded Arti circuits
oniux Namespace isolation, Linux network namespace for --mode isolated
cli-core Shared CLI framework, consistent output formatting and JSON modes
auth-shared Shared authentication, device ID and session management

Optional integrations (enabled with --features kodachi-services):

Service Integration
dns-leak DNS verification during preflight
permission-guard Permission checks during preflight
integrity-check Binary integrity verification
deps-checker Dependency validation
logs-hook Centralized logging
health-control Internet connectivity recovery after identity changes (NetworkRecovery in-process)

Claude Code CLI Provider — No API Key Needed

kodachi-claw includes a built-in Claude Code CLI provider that invokes the installed claude binary as a subprocess. No API key management needed. Claude Code handles authentication internally.

Tor Compatibility Constraint (Backend-Enforced)

claude-code cannot run when Tor routing is active. Backend code explicitly blocks this to prevent deanonymization: - Claude Code CLI (Node.js) does not reliably honor SOCKS proxy env vars. - If allowed with Tor active, traffic could bypass Tor and expose real IP. - Runtime returns: claude-code provider cannot be used with Tor routing active ... Use --skip-anonymity ...

So for Claude Code provider, use --skip-anonymity (or switch to another provider).

How It Works

  1. Lazy path detection - the CLI path is detected on first use (not at startup), so construction never fails
  2. Hardened search order - checks well-known paths first (/usr/local/bin/claude, /usr/bin/claude), then ~/.local/bin/claude, then falls back to which claude
  3. Subprocess invocation - runs claude -p <prompt> --output-format text [--model <model>]
  4. 120-second timeout - prevents hanging on long operations
  5. Secret scrubbing - redacts API keys from error messages

Usage

# Configure kodachi-claw to use Claude Code as the provider
kodachi-claw onboard --provider claude-code

# Use Claude Code directly (requires Tor/anonymity bypass for this provider)
kodachi-claw agent --provider claude-code --message "analyze my security posture" --skip-anonymity

# If you want Tor routing active, use a remote API provider instead
sudo kodachi-claw agent --provider openrouter --message "analyze my security posture"

# List all providers (claude-code shows as local — no API key required)
kodachi-claw providers

Why This Matters

Most AI providers require API keys. On a fresh Kodachi installation, no API keys are configured. The Claude Code CLI provider bypasses this entirely. If Claude Code is installed, kodachi-claw can use it immediately.

For anonymity mode: - Remote HTTP providers (OpenRouter/OpenAI/Gemini/etc.) are designed to run through kodachi-claw Tor SOCKS routing. - claude-code is intentionally blocked when Tor is active. - Local ollama (localhost) may fail while Tor proxy is forced; use --skip-anonymity for local-only inference workflows.

ai-gateway Integration — Safe Command Execution

kodachi-claw integrates with ai-gateway for policy-gated command execution across all Kodachi services. The gateway provides service discovery, risk classification, and approval workflows.

Discovery — Find Commands

# kodachi-claw can discover available commands through ai-gateway
ai-gateway search "check tor status" --limit 1 --json | jq '.data.results[0].invocation'

# Get full command specification
ai-gateway help tor-switch tor-status --json | jq '.data.needs_root,.data.offline_safe,.data.network_touching'

Safe Execution — Validate Then Run

# Step 1: Dry-run validates without executing
ai-gateway run tor-switch --command tor-status --dry-run --json

# Step 2: Execute passive command (no env var needed)
ai-gateway run tor-switch --command tor-status --json

# kodachi-claw integration path through ai-gateway
ai-gateway run kodachi-claw --command status --dry-run --json
ai-gateway run kodachi-claw --command status --json

About sudo for ai-gateway runs

For the exact example above, both of these worked without sudo in backend testing on 2026-02-23: - ai-gateway run tor-switch --command tor-status --dry-run --json - ai-gateway run tor-switch --command tor-status --json

Still, check command metadata first (ai-gateway help <service> <command> --json), and if needs_root is true, prefer sudo for consistent behavior across hosts.

Agent Identity and Capabilities

# Discover what kodachi-claw is allowed to do
ai-gateway capabilities --agent-id kodachi-claw \
  --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --json

Approval Workflow for Dangerous Operations

# Step 1: Human issues a time-limited approval ticket (10 minutes)
TICKET=$(ai-gateway approve issue health-control block-internet \
  --agent-id kodachi-claw --ttl 600 --json | jq -r '.data.ticket')

# Step 2: kodachi-claw executes using identity + ticket
ai-gateway run health-control --command block-internet \
  --agent-id kodachi-claw \
  --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW \
  --approval-ticket "$TICKET" --json

Why This Matters

Without ai-gateway, kodachi-claw executes commands directly. With ai-gateway, every command goes through a policy firewall with three-tier risk classification (Passive/Active/Dangerous), per-agent rate limiting, and human-in-the-loop approval for destructive operations. This adds a safety layer between the autonomous agent and real system operations.

For full ai-gateway workflows, see the ai-gateway Guide.

Scenario 1: First-Time Setup — Onboard and Launch Your Anonymous Agent

Get kodachi-claw running with full Tor anonymity in under 5 minutes.

Step 1: Initialize Workspace

# Interactive setup — walks you through provider selection, API keys, channels
kodachi-claw onboard --interactive

# Quick setup with API key provider
kodachi-claw onboard --api-key sk-... --provider openrouter

# If you will run agent/daemon with sudo, onboard in sudo context too
sudo kodachi-claw onboard --api-key sk-... --provider openrouter
sudo chmod 600 /root/.kodachi-claw/config.toml

# No API key flow (uses installed Claude Code CLI)
kodachi-claw onboard --provider claude-code

# Custom OpenAI-compatible gateway
kodachi-claw onboard --api-key sk-... --provider "custom:https://gateway.example.com"

Step 2: Launch the Agent Through Tor

# Start the agent — boots 10 Tor circuits, randomizes identity, verifies IP/DNS
sudo kodachi-claw agent

# Expected startup sequence:
# ✓ MAC address randomized (was 00:1A:2B:3C:4D:5E → 7A:3F:91:D2:E8:4C)
# ✓ Hostname randomized (was kodachi → xr7-phantom-node)
# ✓ Timezone randomized (was UTC → Pacific/Fiji)
# ✓ Tor pool started: 10 circuits active
# ✓ IP verification passed: exit node 185.xxx.xxx.xxx (Tor)
# ✓ DNS verification passed: no leaks detected
# ✓ Agent ready — all traffic routed through Tor

Step 3: Verify Anonymity

# Check full system status
sudo kodachi-claw status

# JSON output for scripting
sudo kodachi-claw --json-pretty status

Why this matters: Every API call, model request, and channel message goes through embedded Tor circuits. Your real IP, MAC, hostname, and timezone are never exposed.

Scenario 2: Maximum Isolation — Kernel-Level Namespace via Oniux

When standard Tor routing isn't enough, use network namespace isolation to guarantee no traffic bypasses Tor.

Step 1: Launch in Isolated Mode

# Full network namespace — separate kernel network stack
sudo kodachi-claw --mode isolated agent

# Expected output:
# ✓ Creating network namespace via oniux...
# ✓ Namespace active: all traffic forced through Tor at kernel level
# ✓ No bypass possible — even misbehaving libraries are contained

Step 2: Verify Namespace Isolation

# All traffic from the agent process is confined to the Tor namespace
sudo kodachi-claw --mode isolated --json-pretty status

Step 3: Run Autonomous Daemon in Isolation

# Long-running autonomous runtime with kernel-level Tor enforcement
sudo kodachi-claw --mode isolated daemon

Why this matters: In isolated mode, oniux creates a Linux network namespace that forces ALL traffic through Tor at the kernel level. Even if a tool or library tries to make a direct connection, it physically cannot — the kernel blocks it.

Scenario 3: High-Throughput Daemon — Multi-Circuit Load Balancing

Run an autonomous agent across multiple Tor circuits for parallel operations.

Step 1: Start Daemon with 20 Circuits

# 20 Tor circuits for high-throughput channel monitoring
sudo kodachi-claw --tor-instances 20 daemon

# Expected output:
# ✓ Tor pool started: 20 circuits active
# ✓ Gateway listening on 127.0.0.1:3000
# ✓ Channels active: Telegram, Discord, Matrix
# ✓ Scheduler running: 3 cron jobs
# ✓ Heartbeat: every 60s

Step 2: Use Sticky Circuits for Consistent Identity

# Same channel always uses the same exit node — prevents identity flickering
sudo kodachi-claw --tor-instances 20 --circuit-strategy sticky daemon

Step 3: Monitor Circuit Health

# Check all circuits and their status
sudo kodachi-claw --json-pretty status

# Run diagnostics
sudo kodachi-claw doctor

Why this matters: Each Tor circuit has a different exit IP. With round-robin or random strategy, your agent's apparent location changes per request. With sticky, each channel gets a consistent identity while remaining anonymous.

Scenario 4: Identity Management — Randomize, Verify, Restore

Control exactly what gets randomized and restore your original identity on exit.

Step 1: Selective Identity Randomization

# Randomize MAC only (skip hostname and timezone)
sudo kodachi-claw --skip-hostname --skip-timezone agent

# Skip MAC randomization (keep your real MAC, randomize hostname only)
sudo kodachi-claw --skip-mac --skip-timezone agent

# Skip all identity randomization (use current MAC/hostname/timezone)
sudo kodachi-claw --skip-identity agent

Step 2: Auto-Restore on Exit

# Randomize everything, but restore originals when the agent stops
sudo kodachi-claw --restore-on-exit agent

# Expected on shutdown:
# ✓ Restoring MAC address: 7A:3F:91:D2:E8:4C → 00:1A:2B:3C:4D:5E
# ✓ Restoring hostname: xr7-phantom-node → kodachi
# ✓ Restoring timezone: Pacific/Fiji → UTC
# ✓ Tor circuits closed
# ✓ Cleanup complete

Step 3: Skip Everything for Local Testing

# No Tor, no identity randomization — direct connection (testing only!)
sudo kodachi-claw --skip-all agent

Why this matters: --restore-on-exit ensures your system returns to its original state after the agent stops. This is critical for shared machines or when switching between anonymous and normal operations.

Scenario 5: Multi-Channel Anonymous Communication

Deploy your agent across multiple communication channels, all routed through Tor.

Step 1: Add Channels

# Add Telegram channel (backend-verified syntax)
kodachi-claw channel add telegram '{"bot_token":"...","allowed_users":["user1"]}'

# Add additional channels using the same pattern:
# kodachi-claw channel add <provider> '<provider_specific_json>'
# Example providers: discord, slack, matrix

Step 2: Start Daemon with All Channels

# Start autonomous daemon — listens on all configured channels through Tor
sudo kodachi-claw daemon

# Messages from Telegram, Discord, Matrix all arrive through Tor circuits
# Responses go back through Tor — channel providers never see your real IP

Step 3: Check Channel Health

# List active channels
kodachi-claw channel list

# Run channel diagnostics
sudo kodachi-claw channel doctor

Why this matters: Every channel connection (Telegram API, Discord WebSocket, Matrix federation) goes through Tor. The channel providers see a Tor exit node, not your real IP address.

Scenario 6: Scheduled Tasks — Cron Jobs Through Tor

Schedule automated tasks that execute anonymously on a timer.

Step 1: Add Scheduled Tasks

# Run a security check every hour
kodachi-claw cron add "0 * * * *" "check security posture"

# Send a daily report to Telegram at 9am
kodachi-claw cron add "0 9 * * *" "send daily security report"

# Run DNS leak check every 30 minutes (interval in milliseconds)
kodachi-claw cron add-every 1800000 "verify dns integrity"

Step 2: List and Manage Tasks

# List all scheduled tasks
kodachi-claw cron list

# Pause a task
kodachi-claw cron pause 1

# Remove a task
kodachi-claw cron remove 2

Step 3: Run Daemon with Scheduler

# Daemon automatically runs all cron jobs through Tor
sudo kodachi-claw daemon

Why this matters: Scheduled tasks inherit the full anonymity stack — each cron execution goes through Tor with a fresh or reused circuit depending on your instance policy.

Scenario 7: Service Management — Install as System Service

Run kodachi-claw as a persistent system service that starts on boot.

Step 1: Install the Service

# Install as systemd service
sudo kodachi-claw service install

# Start the service
sudo kodachi-claw service start

# Check service status
sudo kodachi-claw service status

Step 2: Service Operates with Full Anonymity

# The service runs with the same anonymity stack:
# - Tor circuits are established on service start
# - Identity is randomized on service start
# - All channels and cron jobs run through Tor
# - Restore-on-exit triggers on service stop

Step 3: Manage the Service

# Stop the service
sudo kodachi-claw service stop

# Uninstall the service
sudo kodachi-claw service uninstall

Why this matters: As a system service, kodachi-claw starts automatically on boot with full anonymity. No manual intervention needed — your agent is always running and always anonymous.

Scenario 8: Diagnostics and Troubleshooting

Diagnose issues with Tor connectivity, channels, and system health.

Step 1: Run Full Diagnostics

# Check daemon, scheduler, and channel freshness
sudo kodachi-claw doctor

# Check AI provider model availability
sudo kodachi-claw doctor models

Step 2: Verbose Status Output

# Detailed status with all Tor circuits, identity state, agent config
sudo kodachi-claw -V status

# JSON output for parsing
sudo kodachi-claw --json-pretty status

Step 3: Test Connectivity Without Starting Agent

# Skip agent startup — just verify anonymity stack works
sudo kodachi-claw --skip-all status

# Test only Tor connectivity
sudo kodachi-claw agent --message "what is my IP?" --json

Why this matters: The doctor command checks all subsystems (Tor circuits, channel connections, scheduler jobs, provider availability) and reports issues before they become problems.

Scenario 9: Internet Recovery — Auto-Heal After Identity Changes

MAC address randomization cycles network interfaces down and up, which can break internet connectivity. kodachi-claw can automatically detect and recover from this.

Step 1: Enable Auto-Recovery

# Auto-recover internet after MAC changes and on shutdown
sudo kodachi-claw --auto-recover-internet --restore-on-exit agent

# Expected startup sequence:
# ✓ MAC address randomized (was 00:1A:2B:3C:4D:5E → 7A:3F:91:D2:E8:4C)
# ✓ Waiting 2s for interfaces to stabilize...
# ✓ Net check: IP ping OK, DNS resolve OK
# ✓ Internet connectivity verified after MAC change
# ✓ Hostname randomized
# ✓ Timezone randomized
# ✓ Tor pool started: 10 circuits active

Step 2: Standalone Recovery Command

# Check connectivity and recover if broken
sudo kodachi-claw recover-internet

# Force recovery (skip connectivity check, go straight to health-control)
sudo kodachi-claw recover-internet --force

# JSON output for automation
sudo kodachi-claw --json recover-internet

Step 3: Override Auto-Recovery

# Disable auto-recovery even if another flag enables it
sudo kodachi-claw --auto-recover-internet --skip-auto-recover-internet agent

How Recovery Works

  1. Net check: Pings 1.1.1.1 (IP layer) and resolves google.com (DNS layer) with 6s timeouts
  2. If connectivity OK: Continues normally
  3. If connectivity lost: Invokes health-control NetworkRecovery in-process (library call, not binary)
  4. Health-control tries: ~10 recovery methods (interface restart, DHCP renew, DNS reset, etc.)
  5. Verification: Runs net check again to confirm recovery
  6. Non-fatal: All outcomes are logged but never abort the agent — connectivity loss is degraded, not fatal

Recovery Points

Trigger When
Post-MAC change After network interface cycling during MAC randomization
Post-identity bootstrap After all identity changes complete (belt-and-suspenders)
Shutdown After identity restore, before Tor teardown
SIGINT/SIGTERM Signal handler runs cleanup path including recovery
Manual kodachi-claw recover-internet subcommand

Why this matters: MAC randomization takes network interfaces down and up. On some hardware or network configurations, connectivity doesn't automatically restore. Auto-recovery ensures your agent always has internet access without manual intervention.

Scenario 10: Interactive Mode Workflow — Start, Operate, Exit Cleanly

Run a real interactive session with the minimum steps, then exit safely with identity cleanup.

Step 1: Ensure Onboarding Is Complete

# Use wizard if first run
kodachi-claw onboard --interactive

# Or fast path with your preferred provider
kodachi-claw onboard --provider claude-code

Step 2: Start Interactive Agent Mode

# Full anonymous interactive mode
sudo kodachi-claw agent

# One-shot mode when you only need a single answer
sudo kodachi-claw agent --message "check my public IP through Tor"

Step 3: Use In-Session Controls

# Run these inside agent interactive mode
/help
/clear
/quit

Step 4: Verify Post-Exit State

# If you started with --restore-on-exit, verify system identity/state after quit
sudo kodachi-claw status

Why this matters: This flow gives you an operational routine for daily use: onboard once, run anonymous interactive work, use slash controls, then exit and verify cleanup.

System Information

Component Version License
kodachi-claw 9.0.1 Proprietary - Kodachi OS
Arti (Tor) 1.9.0 MIT/Apache-2.0
oniux 0.8.1 MIT/Apache-2.0
Documentation 9.0.1 All Rights Reserved

Train External AI on Kodachi Commands

If you want another AI model to be aware of Kodachi command capabilities, use these generated exports:

Dataset Purpose Link
all_rust_binary_commands.csv Flat command catalog across all Rust binaries (good for intent training and embedding pipelines) Open CSV
all_rust_binary_info.json Structured metadata for binaries, commands, flags, examples, and usage Open JSON