kodachi-claw

Kodachi hardened AI runtime with embedded anonymity controls

Version: 9.0.1 | Size: 28.3MB | Author: theonlyhennygod

License: Proprietary - Kodachi OS | Website: https://github.com/WMAL/Linux-Kodachi

File Information

Property	Value
Binary Name	kodachi-claw
Version	9.0.1
Build Date	2026-02-21T23:54:07.928539571Z
Rust Version	1.82.0
File Size	28.3MB
JSON Data	View Raw JSON

SHA256 Checksum

f62a591c302a284dbfe11b1b32251e85d20401eedcbbbb95a1923d22a43ccc5f

Features

Feature	Description
Feature	Embedded Arti-first Tor anonymity runtime
Feature	Multi-circuit load balancing across Tor instances
Feature	Isolated per-request circuit assignment
Feature	Single-circuit mode for consistent identity
Feature	Automatic MAC address randomization
Feature	Hostname and timezone randomization
Feature	IP and DNS leak verification
Feature	OPSEC filter (outbound identity leak redaction)
Feature	HMAC-SHA256 tamper-evident audit logging
Feature	Authentication via online-auth integration
Feature	Integrity checking via integrity-check integration
Feature	Permission monitoring via permission-guard integration
Feature	Centralized logging via logs-hook integration
Feature	12+ AI providers (OpenAI, Anthropic, Gemini, Ollama, OpenRouter, etc.)
Feature	14 communication channels (Telegram, Discord, Slack, Matrix, etc.)
Feature	Hybrid memory (SQLite FTS5 + vector cosine similarity)
Feature	ChaCha20-Poly1305 encrypted secret store
Feature	Sandbox backends (Landlock, Bubblewrap, Firejail, Docker)
Feature	Cron job scheduler with security allowlists
Feature	Gateway server with rate limiting and idempotency
Feature	Hardware peripherals (STM32, RPi GPIO, robotics)
Feature	Configurable circuit assignment strategies
Feature	Identity restoration on shutdown
Feature	Retry and timeout controls for network operations
Feature	JSON output mode for automation

Security Features

Feature	Description
Authentication	In-process Kodachi auth with auto-recovery, device ID verification
Encryption	ChaCha20-Poly1305 AEAD, TLS 1.3 via Arti, HMAC-SHA256 webhooks
Inputvalidation	Command allowlists, path sanitization, SSRF protection
Ratelimiting	Sliding-window rate limiting with configurable thresholds

System Requirements

Requirement	Value
OS	Linux (Kodachi OS, Debian-based distributions)
Privileges	Root/sudo required for MAC/hostname/timezone randomization
Dependencies	macchanger (MAC randomization), ip (network interface control), hostnamectl or hostname (hostname management), timedatectl (timezone management), online-auth (authentication service), integrity-check (file integrity verification), permission-guard (permission monitoring), logs-hook (centralized logging)

Global Options

Flag	Description
`-h, --help`	Print help and exit
`-v, --version`	Print version and exit
`-n, --info`	Show detailed program information and exit
`-e, --examples`	Show comprehensive command examples and exit
`--json`	Output startup status as compact JSON
`--json-pretty`	Output startup status as pretty JSON
`--json-human`	Output startup status as human-readable JSON
`--mode <MODE>`	Anonymity runtime mode [default: multi-circuit] [possible values: multi-circuit, isolated, single]
`--tor-instances <N>`	Tor pool size (ignored in single mode) [default: 10]
`--instance-policy <POLICY>`	Instance reuse policy [default: reuse] [possible values: reuse, new, mixed]
`--instance-prefix <PREFIX>`	Instance name prefix [default: kodachi-claw-instance]
`--access-mode <MODE>`	Access mode for execution path [default: system] [possible values: system, gateway]
`--auth-mode <MODE>`	Authentication mode [default: auto] [possible values: auto, required]
`--skip-mac`	Skip MAC randomization
`--skip-hostname`	Skip hostname randomization
`--skip-timezone`	Skip timezone randomization
`--skip-identity`	Skip all identity randomization
`--skip-tor`	Skip embedded Tor startup
`--skip-ip-check`	Skip IP/Tor verification checks [aliases: --skip-verify]
`--skip-dns-check`	Skip DNS verification checks
`--skip-anonymity`	Skip all anonymity bootstrap behavior
`--skip-integrity-check`	Skip integrity check during preflight
`--skip-permission-check`	Skip permission check during preflight
`--restore-on-exit`	Restore MAC/hostname/timezone state on shutdown
`--auto-recover-internet`	Auto-check and recover internet after identity changes and on exit
`--skip-auto-recover-internet`	Disable auto-recover-internet (overrides --auto-recover-internet)
`-V, --verbose`	Enable verbose logging output
`-q, --quiet`	Suppress all non-error output
`--no-color`	Disable colored output
`--timeout <SECONDS>`	Timeout in seconds for network operations [default: 30]
`--retry <COUNT>`	Number of retries for network operations [default: 3]
`--circuit-strategy <STRATEGY>`	Circuit assignment strategy for multi-circuit mode [default: round-robin] [possible values: round-robin, random, least-used, sticky]
`--skip-all`	Skip all anonymity startup phases except OS authentication

Commands

`onboard`

Initialize your workspace and configuration

Usage:

kodachi-claw onboard

`agent`

Start the AI agent loop

Usage:

kodachi-claw agent

`gateway`

Start the gateway server (webhooks, websockets)

Usage:

kodachi-claw gateway

`daemon`

Start long-running autonomous runtime (gateway + channels + heartbeat + scheduler)

Usage:

kodachi-claw daemon

`service`

Manage OS service lifecycle (launchd/systemd user service)

Usage:

kodachi-claw service

`doctor`

Run diagnostics for daemon/scheduler/channel freshness

Usage:

kodachi-claw doctor

`status`

Show system status (full details)

Usage:

kodachi-claw status

`cron`

Configure and manage scheduled tasks

Usage:

kodachi-claw cron

`models`

Manage provider model catalogs

Usage:

kodachi-claw models

`providers`

List supported AI providers

Usage:

kodachi-claw providers

`channel`

Manage channels (telegram, discord, slack)

Usage:

kodachi-claw channel

`integrations`

Browse 50+ integrations

Usage:

kodachi-claw integrations

`skills`

Manage skills (user-defined capabilities)

Usage:

kodachi-claw skills

`migrate`

Migrate data from other agent runtimes

Usage:

kodachi-claw migrate

`auth`

Manage provider subscription authentication profiles

Usage:

kodachi-claw auth

`hardware`

Discover and introspect USB hardware

Usage:

kodachi-claw hardware

`peripheral`

Manage hardware peripherals (STM32, RPi GPIO, etc.)

Usage:

kodachi-claw peripheral

`help`

Print this message or the help of the given subcommand(s)

Usage:

kodachi-claw help

Examples

AI Agent

Start and interact with the AI agent

Interactive session with full anonymity

sudo kodachi-claw agent

Expected Output: Tor bootstrapped, identity randomized, agent ready

Note

Requires onboarding first: kodachi-claw onboard

Single message mode

sudo kodachi-claw agent --message "What is my IP?"

Expected Output: Response through Tor-routed connection

Specific provider/model

sudo kodachi-claw agent --provider anthropic --model claude-sonnet-4-5-20250929

Expected Output: Agent session using Anthropic Claude

Local offline model

sudo kodachi-claw agent --message "scan ports" --provider ollama --model llama3

Expected Output: Agent runs with local model, Tor still active for tools

Low temperature for deterministic output

sudo kodachi-claw agent --temperature 0.2 --message "write secure code"

Expected Output: Agent runs with temperature 0.2

Hardware peripheral attached

sudo kodachi-claw agent --peripheral nucleo-f401re:/dev/ttyACM0 --message "blink LED"

Expected Output: Agent with STM32 board attached

Use installed Claude Code CLI (no API key)

sudo kodachi-claw agent --provider claude-code --message "What is my IP?" --skip-anonymity

Expected Output: Agent uses local Claude Code CLI for inference

Note

Requires claude CLI installed. No API key needed

Daemon & Gateway

Long-running services and webhook endpoints

Full daemon with all channels

sudo kodachi-claw daemon

Expected Output: Daemon running: all configured channels active

Note

Listens on all configured channels simultaneously

Custom gateway port

sudo kodachi-claw daemon --port 8080

Expected Output: Gateway + channels + heartbeat + scheduler running

Bind to all interfaces

sudo kodachi-claw daemon --host 0.0.0.0 --port 9090

Expected Output: Daemon bound to 0.0.0.0:9090

Gateway-only (webhook/WebSocket)

sudo kodachi-claw gateway --port 9090

Expected Output: Gateway accepting webhook requests on :9090

Install as systemd service

sudo kodachi-claw service install && sudo kodachi-claw service start

Expected Output: Service installed with auto-restart on failure

Setup & Onboarding

First-time configuration and channel management

Full wizard (9 steps)

kodachi-claw onboard --interactive

Expected Output: Guided 9-step setup wizard

Note

Run this first before using agent or daemon

Quick setup

kodachi-claw onboard --api-key sk-... --provider openrouter

Expected Output: Config created with OpenRouter provider

Quick setup with memory backend

kodachi-claw onboard --api-key sk-... --provider anthropic --memory sqlite

Expected Output: Config created with Anthropic + SQLite memory

Quick setup with Claude Code CLI (no API key)

kodachi-claw onboard --provider claude-code

Expected Output: Config created with claude-code provider

Note

No API key needed -- Claude Code handles auth internally

Reconfigure channels only

kodachi-claw onboard --channels-only

Expected Output: Channel configuration updated

Bind Telegram identity

kodachi-claw channel bind-telegram myusername

Expected Output: Telegram user bound to allowlist

Status & Diagnostics

System status, health checks, and diagnostics

Full status including MAC, hostname, timezone, IP, auth

sudo kodachi-claw status

Expected Output: Complete system status with identity info

Basic status without security/identity info

kodachi-claw status --skip

Expected Output: Config and channel status only

JSON status for automation

sudo kodachi-claw --json-pretty status

Expected Output: Pretty-printed JSON envelope with status data

Run health diagnostics

kodachi-claw doctor

Expected Output: Diagnostic report for daemon/scheduler/channels

Probe model availability

sudo kodachi-claw doctor models --provider openai

Expected Output: Available models for the specified provider

Scheduled Tasks

Configure and manage cron-style scheduled tasks

List all scheduled tasks

kodachi-claw cron list

Expected Output: Table of scheduled tasks with status

Run every 6 hours

kodachi-claw cron add "0 */6 * * *" "check disk space"

Expected Output: Task added with cron schedule

Weekly with timezone

kodachi-claw cron add "0 9 * * 1" "weekly report" --tz America/New_York

Expected Output: Task scheduled for Monday 9AM ET

One-shot at specific time

kodachi-claw cron add-at "2026-03-01T09:00:00Z" "deploy update"

Expected Output: One-time task scheduled

Every 5 minutes

kodachi-claw cron add-every 300000 "heartbeat check"

Expected Output: Interval task added (300s)

One-shot after 30 minutes

kodachi-claw cron once 30m "backup workspace"

Expected Output: One-time delayed task scheduled

Pause/resume tasks

kodachi-claw cron pause <ID> && kodachi-claw cron resume <ID>

Expected Output: Task paused/resumed

Models & Providers

Manage AI model catalogs and providers

Refresh model catalog from default provider

kodachi-claw models refresh

Expected Output: Model catalog updated

Force refresh from specific provider

sudo kodachi-claw models refresh --provider openai --force

Expected Output: OpenAI model catalog force-refreshed

List all 12+ supported AI providers

kodachi-claw providers

Expected Output: Provider table with active marker

Check cached model availability

kodachi-claw doctor models --use-cache

Expected Output: Model availability from cache

Channel Management

Configure and manage communication channels

List configured channels

kodachi-claw channel list

Expected Output: Channel status table

Start all configured channels

sudo kodachi-claw channel start

Expected Output: All channels listening

Health check all channels

sudo kodachi-claw channel doctor

Expected Output: Channel health report

Add Telegram channel

kodachi-claw channel add telegram '{"bot_token":"...","allowed_users":["user1"]}'

Expected Output: Telegram channel configured

Remove a channel

kodachi-claw channel remove discord

Expected Output: Discord channel removed

Bind Telegram user ID to allowlist

kodachi-claw channel bind-telegram 123456789

Expected Output: Telegram user ID bound

Authentication

Manage provider authentication profiles

OAuth login

kodachi-claw auth login --provider openai-codex

Expected Output: Browser-based OAuth flow started

Device code flow

kodachi-claw auth login --provider openai-codex --device-code

Expected Output: Device code displayed for authorization

Paste API key

kodachi-claw auth paste-token --provider anthropic --auth-kind api-key

Expected Output: API key stored securely

Interactive token entry

kodachi-claw auth setup-token --provider anthropic

Expected Output: Token stored in encrypted secret store

Refresh access token

kodachi-claw auth refresh --provider openai-codex

Expected Output: Token refreshed successfully

List all auth profiles

kodachi-claw auth list

Expected Output: Auth profile table with active markers

Show active profile and token expiry

kodachi-claw auth status

Expected Output: Profile status with expiration info

Remove auth profile

kodachi-claw auth logout --provider openai-codex

Expected Output: Auth profile removed

Skills Management

Manage user-defined capabilities

List installed skills

kodachi-claw skills list

Expected Output: Installed skills table

Install from GitHub

kodachi-claw skills install https://github.com/user/skill-repo

Expected Output: Skill installed and registered

Remove installed skill

kodachi-claw skills remove my-skill

Expected Output: Skill removed

Integrations

Browse and manage service integrations

Show GitHub integration details

kodachi-claw integrations info github

Expected Output: GitHub integration configuration and status

Show Jira integration details

kodachi-claw integrations info jira

Expected Output: Jira integration configuration and status

Migration

Import data from other agent runtimes

Preview migration without writing

kodachi-claw migrate openclaw --dry-run

Expected Output: Migration preview with changes listed

Import from OpenClaw

kodachi-claw migrate openclaw --source /path/to/openclaw/workspace

Expected Output: Data imported from OpenClaw workspace

Hardware & Peripherals

Discover and manage hardware devices

Enumerate USB devices and known boards

kodachi-claw hardware discover

Expected Output: Detected hardware devices

Introspect specific device

kodachi-claw hardware introspect /dev/ttyACM0

Expected Output: Device capabilities and firmware info

Get chip info

kodachi-claw hardware info --chip stm32f401re

Expected Output: Chip specifications and pinout

List configured peripherals

kodachi-claw peripheral list

Expected Output: Configured peripheral boards

Add STM32 board

kodachi-claw peripheral add nucleo-f401re /dev/ttyACM0

Expected Output: Peripheral added to config

Flash firmware

kodachi-claw peripheral flash --port /dev/ttyACM0

Expected Output: Firmware flashed to device

Service Lifecycle

Install and manage as a system service

Install as systemd/launchd service

sudo kodachi-claw service install

Expected Output: Service unit installed

Start the service

sudo kodachi-claw service start

Expected Output: Service started

Stop the service

sudo kodachi-claw service stop

Expected Output: Service stopped

Check service status

kodachi-claw service status

Expected Output: Service running/stopped status

Uninstall the service

sudo kodachi-claw service uninstall

Expected Output: Service unit removed

Anonymity & Tor Modes

Control Tor instances, circuits, and identity randomization

10 parallel circuits

sudo kodachi-claw --mode multi-circuit --tor-instances 10 agent

Expected Output: 10 Arti instances bootstrapped, traffic distributed across circuits

Note

Default mode. Each tool/channel gets a different circuit

Namespace isolation via oniux

sudo kodachi-claw --mode isolated agent

Expected Output: Namespace-isolated agent with embedded Tor

Note

Requires root or CAP_NET_ADMIN

Single circuit (low-resource)

sudo kodachi-claw --mode single --tor-instances 1 agent

Expected Output: Single Arti instance, minimal memory usage

Sticky circuit assignment

sudo kodachi-claw --circuit-strategy sticky daemon

Expected Output: Sticky circuit assignment per tool/channel

Note

Strategies: round-robin (default), random, least-used, sticky

Random assignment across 5 circuits

sudo kodachi-claw --circuit-strategy random --tor-instances 5 agent

Expected Output: Random circuit selection per request

Restore identity on exit

sudo kodachi-claw --restore-on-exit agent

Expected Output: Identity restored after session ends

Note

Without this flag, spoofed identity persists after exit

Selective identity spoofing

sudo kodachi-claw --skip-mac --skip-hostname agent

Expected Output: Only timezone randomized, Tor still active

Gateway access with required auth

sudo kodachi-claw --access-mode gateway --auth-mode required daemon

Expected Output: Gateway mode with mandatory authentication

Check and recover internet connectivity

sudo kodachi-claw recover-internet

Expected Output: Internet connectivity is working / Internet recovered successfully

Note

Invokes health-control recover-internet if connectivity is lost

Force recovery even if internet appears working

sudo kodachi-claw recover-internet --force

Expected Output: Internet recovered successfully

Note

Skips initial check, goes straight to health-control recovery

Check/recover with JSON output

sudo kodachi-claw --json recover-internet

Expected Output: {status: connected, recovery_needed: false, ...}

Note

Returns JSON envelope with connectivity status and recovery details

Auto-recover internet after identity changes

sudo kodachi-claw --auto-recover-internet --restore-on-exit agent

Expected Output: Net check after MAC change, recovery on exit

Note

Checks connectivity after MAC randomization and during shutdown

Skip flag overrides auto-recover

sudo kodachi-claw --auto-recover-internet --skip-auto-recover-internet agent

Expected Output: Agent runs without auto-recovery (skip wins)

Note

--skip-auto-recover-internet takes precedence over --auto-recover-internet

Skip Controls

Disable specific startup phases for debugging or testing

No Tor, no identity changes

sudo kodachi-claw --skip-anonymity agent

Expected Output: Agent runs without Tor, no identity changes

Note

WARNING: No privacy protection. Local testing only

Skip all startup phases

sudo kodachi-claw --skip-all status

Expected Output: Status with no anonymity bootstrap

Quick status without Tor

sudo kodachi-claw --skip-tor --skip-identity status

Expected Output: Status report with auth check only

Skip verification checks

sudo kodachi-claw --skip-dns-check --skip-ip-check agent

Expected Output: Tor starts but IP/DNS not verified

Skip preflight checks

sudo kodachi-claw --skip-integrity-check --skip-permission-check agent

Expected Output: Agent starts without preflight verification

Output & Automation

JSON output modes for scripting and CI/CD

Compact JSON for scripting

sudo kodachi-claw --json status

Expected Output: {"status":"success",...}

Pretty-printed JSON

sudo kodachi-claw --json-pretty status

Expected Output: Formatted JSON with indentation

Human-annotated JSON

sudo kodachi-claw --json-human status

Expected Output: JSON with human-readable annotations

Note

Also: --json (compact), --json-pretty (indented)

Verbose logging

sudo kodachi-claw -V --verbose agent --message "debug this"

Expected Output: Debug-level log output

Suppress non-error output

sudo kodachi-claw -q --quiet daemon

Expected Output: Only error messages shown

Custom network settings

sudo kodachi-claw --timeout 60 --retry 5 --instance-policy new daemon

Expected Output: 60s timeout, 5 retries, fresh instances

Note

Policies: reuse (default), new, mixed

AI Gateway Providers

Route requests through AI gateway proxies (Cloudflare, Vercel, custom OpenAI-compatible endpoints)

Use Cloudflare AI Gateway

sudo kodachi-claw agent --provider cloudflare --message "summarize this"

Expected Output: Request routed through gateway.ai.cloudflare.com/v1 over Tor

Note

Set CLOUDFLARE_API_KEY env var or api_key in config. Supports all Cloudflare-hosted models

Use Vercel AI Gateway

sudo kodachi-claw agent --provider vercel --message "explain this code"

Expected Output: Request routed through api.vercel.ai over Tor

Note

Set VERCEL_API_KEY env var or api_key in config

Any OpenAI-compatible gateway via custom URL

sudo kodachi-claw agent --provider "custom:https://your-gateway.example.com" --message "hello"

Expected Output: Request sent to your-gateway.example.com/v1/chat/completions over Tor

Note

Works with vLLM, LiteLLM, Azure OpenAI, any /v1/chat/completions endpoint

Anthropic-compatible proxy (corporate/self-hosted)

sudo kodachi-claw agent --provider "anthropic-custom:https://llm-proxy.corp.example.com" --message "review PR"

Expected Output: Request sent to llm-proxy.corp.example.com using Anthropic API format

Note

For proxies that speak the Anthropic Messages API instead of OpenAI format

Groq ultra-fast inference gateway

sudo kodachi-claw daemon --provider groq

Expected Output: Daemon running with Groq LPU inference, all channels active

Note

Set GROQ_API_KEY. Ultra-low latency for supported models

Together AI inference gateway

sudo kodachi-claw agent --provider together --model meta-llama/Llama-3-70b-chat-hf --message "analyze"

Expected Output: Request routed through Together AI over Tor

Note

Set TOGETHER_API_KEY. Supports 100+ open models

Fireworks AI inference gateway

sudo kodachi-claw agent --provider fireworks --model accounts/fireworks/models/llama-v3-70b-instruct --message "write tests"

Expected Output: Request routed through Fireworks AI over Tor

Note

Set FIREWORKS_API_KEY. Optimized for fast open-model inference

Onboard with a custom AI gateway

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

Expected Output: Config created with custom gateway as default provider

Note

The custom URL is stored in config.toml as default_provider

List all supported AI gateway providers

kodachi-claw providers

Expected Output: Table showing 30+ providers including Cloudflare, Vercel, Groq, Together, Fireworks, Mistral, xAI, and more

Note

Use custom: prefix for unlisted OpenAI-compatible gateways

Environment Variables

Variable	Description	Default	Values
`RUST_LOG`	Set logging level	info	trace, debug, info, warn, error

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Permission denied