kodachi-claw

Kodachi hardened AI runtime with embedded anonymity controls

Version: 9.0.1 | Size: 28.5MB | 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-26T08:01:57.598726320Z
Rust Version	1.82.0
File Size	28.5MB
JSON Data	View Raw JSON

SHA256 Checksum

4fa8049ed9b757466d9431151232b94436a2382cde7fce122373c90143335242

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

`tor`

Control Tor instances via tor-switch

Usage:

kodachi-claw tor

`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 (includes kodachi-ai local provider when built with --features kodachi-ai)

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

`recover-internet`

Check internet connectivity and recover if broken (invokes health-control)

Usage:

kodachi-claw recover-internet

`help`

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

Usage:

kodachi-claw help

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: AI Agent

Start and interact with the AI agent

Step 1: Interactive session with full anonymity

sudo kodachi-claw agent

Expected Output: Tor bootstrapped, identity randomized, agent ready

Note

Requires onboarding first: kodachi-claw onboard

Step 2: Single message mode

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

Expected Output: Response through Tor-routed connection

Step 3: Specific provider/model

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

Expected Output: Agent session using Anthropic Claude

Step 4: 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

Step 5: Low temperature for deterministic output

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

Expected Output: Agent runs with temperature 0.2

Step 6: Hardware peripheral attached

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

Expected Output: Agent with STM32 board attached

Step 7: 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

Scenario 2: Daemon & Gateway

Long-running services and webhook endpoints

Step 1: Full daemon with all channels

sudo kodachi-claw daemon

Expected Output: Daemon running: all configured channels active

Note

Listens on all configured channels simultaneously

Step 2: Custom gateway port

sudo kodachi-claw daemon --port 8080

Expected Output: Gateway + channels + heartbeat + scheduler running

Step 3: 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

Step 4: Gateway-only (webhook/WebSocket)

sudo kodachi-claw gateway --port 9090

Expected Output: Gateway accepting webhook requests on :9090

Step 5: Install as systemd service

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

Expected Output: Service installed with auto-restart on failure

Scenario 3: Setup & Onboarding

First-time configuration and channel management

Step 1: Full wizard (9 steps)

kodachi-claw onboard --interactive

Expected Output: Guided 9-step setup wizard

Note

Run this first before using agent or daemon

Step 2: Quick setup

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

Expected Output: Config created with OpenRouter provider

Step 3: Quick setup with memory backend

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

Expected Output: Config created with Anthropic + SQLite memory

Step 4: 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

Step 5: Reconfigure channels only

kodachi-claw onboard --channels-only

Expected Output: Channel configuration updated

Step 6: Bind Telegram identity

kodachi-claw channel bind-telegram myusername

Expected Output: Telegram user bound to allowlist

Scenario 4: Status & Diagnostics

System status, health checks, and diagnostics

Step 1: Full status including MAC, hostname, timezone, IP, auth

sudo kodachi-claw status

Expected Output: Complete system status with identity info

Step 2: Basic status without security/identity info

kodachi-claw status --skip

Expected Output: Config and channel status only

Step 3: JSON status for automation

sudo kodachi-claw --json-pretty status

Expected Output: Pretty-printed JSON envelope with status data

Step 4: Run health diagnostics

kodachi-claw doctor

Expected Output: Diagnostic report for daemon/scheduler/channels

Step 5: Probe model availability

sudo kodachi-claw doctor models --provider openai

Expected Output: Available models for the specified provider

Scenario 5: Scheduled Tasks

Configure and manage cron-style scheduled tasks

Step 1: List all scheduled tasks

kodachi-claw cron list

Expected Output: Table of scheduled tasks with status

Step 2: Run every 6 hours

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

Expected Output: Task added with cron schedule

Step 3: Weekly with timezone

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

Expected Output: Task scheduled for Monday 9AM ET

Step 4: One-shot at specific time

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

Expected Output: One-time task scheduled

Step 5: Every 5 minutes

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

Expected Output: Interval task added (300s)

Step 6: One-shot after 30 minutes

kodachi-claw cron once 30m "backup workspace"

Expected Output: One-time delayed task scheduled

Step 7: Pause/resume tasks

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

Expected Output: Task paused/resumed

Scenario 6: Models & Providers

Manage AI model catalogs and providers

Step 1: Refresh model catalog from default provider

kodachi-claw models refresh

Expected Output: Model catalog updated

Step 2: Force refresh from specific provider

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

Expected Output: OpenAI model catalog force-refreshed

Step 3: List all 12+ supported AI providers

kodachi-claw providers

Expected Output: Provider table with active marker

Step 4: Check cached model availability

kodachi-claw doctor models --use-cache

Expected Output: Model availability from cache

Scenario 7: Channel Management

Configure and manage communication channels

Step 1: List configured channels

kodachi-claw channel list

Expected Output: Channel status table

Step 2: Start all configured channels

sudo kodachi-claw channel start

Expected Output: All channels listening

Step 3: Health check all channels

sudo kodachi-claw channel doctor

Expected Output: Channel health report

Step 4: Add Telegram channel

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

Expected Output: Telegram channel configured

Step 5: Remove a channel

kodachi-claw channel remove discord

Expected Output: Discord channel removed

Step 6: Bind Telegram user ID to allowlist

kodachi-claw channel bind-telegram 123456789

Expected Output: Telegram user ID bound

Scenario 8: Authentication

Manage provider authentication profiles

kodachi-claw auth login --provider openai-codex

Expected Output: Browser-based OAuth flow started

Step 2: Device code flow

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

Expected Output: Device code displayed for authorization

Step 3: Paste API key

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

Expected Output: API key stored securely

Step 4: Interactive token entry

kodachi-claw auth setup-token --provider anthropic

Expected Output: Token stored in encrypted secret store

Step 5: Refresh access token

kodachi-claw auth refresh --provider openai-codex

Expected Output: Token refreshed successfully

Step 6: List all auth profiles

kodachi-claw auth list

Expected Output: Auth profile table with active markers

Step 7: Show active profile and token expiry

kodachi-claw auth status

Expected Output: Profile status with expiration info

Step 8: Remove auth profile

kodachi-claw auth logout --provider openai-codex

Expected Output: Auth profile removed

Scenario 9: Skills Management

Manage user-defined capabilities

Step 1: List installed skills

kodachi-claw skills list

Expected Output: Installed skills table

Step 2: Install from GitHub

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

Expected Output: Skill installed and registered

Step 3: Remove installed skill

kodachi-claw skills remove my-skill

Expected Output: Skill removed

Scenario 10: Integrations

Browse and manage service integrations

Step 1: Show GitHub integration details

kodachi-claw integrations info github

Expected Output: GitHub integration configuration and status

Step 2: Show Jira integration details

kodachi-claw integrations info jira

Expected Output: Jira integration configuration and status

Scenario 11: Migration

Import data from other agent runtimes

Step 1: Preview migration without writing

kodachi-claw migrate openclaw --dry-run

Expected Output: Migration preview with changes listed

Step 2: Import from OpenClaw

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

Expected Output: Data imported from OpenClaw workspace

Scenario 12: Hardware & Peripherals

Discover and manage hardware devices

Step 1: Enumerate USB devices and known boards

kodachi-claw hardware discover

Expected Output: Detected hardware devices

Step 2: Introspect specific device

kodachi-claw hardware introspect /dev/ttyACM0

Expected Output: Device capabilities and firmware info

Step 3: Get chip info

kodachi-claw hardware info --chip stm32f401re

Expected Output: Chip specifications and pinout

Step 4: List configured peripherals

kodachi-claw peripheral list

Expected Output: Configured peripheral boards

Step 5: Add STM32 board

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

Expected Output: Peripheral added to config

Step 6: Flash firmware

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

Expected Output: Firmware flashed to device

Scenario 13: Service Lifecycle

Install and manage as a system service

Step 1: Install as systemd/launchd service

sudo kodachi-claw service install

Expected Output: Service unit installed

Step 2: Start the service

sudo kodachi-claw service start

Expected Output: Service started

Step 3: Stop the service

sudo kodachi-claw service stop

Expected Output: Service stopped

Step 4: Check service status

kodachi-claw service status

Expected Output: Service running/stopped status

Step 5: Uninstall the service

sudo kodachi-claw service uninstall

Expected Output: Service unit removed

Scenario 14: Tor Instance Control

Control all Tor instances directly from kodachi-claw

Step 1: List all known Tor instances

sudo kodachi-claw tor list-instances

Expected Output: Table of instance tags and status

Step 2: List instances with current Tor exit IP

sudo kodachi-claw tor list-instances-with-ip

Expected Output: Instance table with live Tor IP addresses

Step 3: Start every Tor instance

sudo kodachi-claw tor start-all-instances

Expected Output: All configured Tor instances started

Step 4: Stop every Tor instance

sudo kodachi-claw tor stop-all-instances

Expected Output: All configured Tor instances stopped

Step 5: Delete all non-default Tor instances

sudo kodachi-claw tor delete-all-instances

Expected Output: Custom Tor instances deleted

Step 6: Delete all instances including default

sudo kodachi-claw tor delete-all-instances-with-default

Expected Output: All Tor instances deleted, including default

Note

Use when you want a full Tor instance reset

Step 7: Automation-friendly Tor instance inventory

sudo kodachi-claw --json-pretty tor list-instances-with-ip

Expected Output: JSON envelope with instance and IP details

Scenario 15: Anonymity & Tor Modes

Control Tor instances, circuits, and identity randomization

Step 1: 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

Step 2: 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

Step 3: Single circuit (low-resource)

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

Expected Output: Single Arti instance, minimal memory usage

Step 4: 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

Step 5: Random assignment across 5 circuits

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

Expected Output: Random circuit selection per request

Step 6: 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

Step 7: Selective identity spoofing

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

Expected Output: Only timezone randomized, Tor still active

Step 8: Gateway access with required auth

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

Expected Output: Gateway mode with mandatory authentication

Step 9: 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

Step 10: 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

Step 11: 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

Step 12: 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

Step 13: 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

Scenario 16: Skip Controls

Disable specific startup phases for debugging or testing

Step 1: 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

Step 2: Skip all startup phases

sudo kodachi-claw --skip-all status

Expected Output: Status with no anonymity bootstrap

Step 3: Quick status without Tor

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

Expected Output: Status report with auth check only

Step 4: Skip verification checks

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

Expected Output: Tor starts but IP/DNS not verified

Step 5: Skip preflight checks

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

Expected Output: Agent starts without preflight verification

Scenario 17: Output & Automation

JSON output modes for scripting and CI/CD

Step 1: Compact JSON for scripting

sudo kodachi-claw --json status

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

Step 2: Pretty-printed JSON

sudo kodachi-claw --json-pretty status

Expected Output: Formatted JSON with indentation

Step 3: Human-annotated JSON

sudo kodachi-claw --json-human status

Expected Output: JSON with human-readable annotations

Note

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

Step 4: Verbose logging

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

Expected Output: Debug-level log output

Step 5: Suppress non-error output

sudo kodachi-claw -q --quiet daemon

Expected Output: Only error messages shown

Step 6: 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

Scenario 18: AI Gateway Providers

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

Step 1: 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

Step 2: 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

Step 3: 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

Step 4: 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

Step 5: Groq ultra-fast inference gateway

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

Expected Output: Agent response generated with Groq LPU inference

Note

Set GROQ_API_KEY. Ultra-low latency for supported models

Step 6: 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

Step 7: 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

Step 8: 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

Step 9: 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

Scenario 19: Local AI (kodachi-ai)

Run with local AI models — no API key required. Build with: cargo build --features kodachi-ai

Step 1: Local AI agent (auto-detects ONNX/GGUF models)

sudo kodachi-claw agent --provider kodachi-ai

Expected Output: 🦀 Kodachi Claw Interactive Mode (local: ONNX + Qwen 3B)

Note

No API key needed. Auto-detects: Claude CLI > Mistral.rs > Local LLM > ONNX > TF-IDF

Step 2: NLP-routed command execution

sudo kodachi-claw agent --provider kodachi-ai --message "switch to Tor"

Expected Output: NLP classifies intent, matches kodachi service commands, executes via gateway-core

Note

High-confidence NLP matches bypass the AI model for instant command routing

Step 3: Onboard with local AI (zero API keys)

kodachi-claw onboard --provider kodachi-ai

Expected Output: Config created with kodachi-ai provider — fully offline capable

Note

No network needed for AI inference. Tor still used for anonymity

Step 4: List available local AI models (interactive command)

/models

Expected Output: Model list: all-MiniLM-L6-v2.onnx (90MB), kodachi-intent-classifier.onnx (67MB), Qwen2.5-3B (2.1GB)

Note

Run inside agent interactive mode. Calls ai-trainer subprocess

Step 5: Download a GGUF model for local inference (interactive command)

/models download Qwen2.5-3B

Expected Output: Downloading Qwen2.5-3B... done

Note

Run inside agent interactive mode. Downloads to models directory

Step 6: Retrain NLP embeddings from latest command data (interactive command)

/train

Expected Output: Training embeddings... 458 commands processed, model saved

Note

Run inside agent interactive mode. Calls ai-trainer subprocess

Step 7: Force specific AI tier (ONNX)

sudo kodachi-claw agent --provider kodachi-ai --tier onnx

Expected Output: Agent using ONNX classifier model only

Note

Available tiers: onnx, mistral, genai, tfidf. Auto-fallback if unavailable

Step 8: Force TF-IDF fallback (no neural models)

sudo kodachi-claw agent --provider kodachi-ai --tier tfidf

Expected Output: Agent using TF-IDF keyword matching only

Note

Fastest but lowest accuracy. Useful for low-resource environments

Scenario 20: Interactive Mode Commands

Slash commands available inside agent interactive mode

Step 1: Show available interactive commands

/help

Expected Output: List of all slash commands with descriptions

Note

Run inside agent mode prompt

Step 2: Clear conversation history

/clear

Expected Output: Conversation history cleared

Note

Resets context for new conversation thread

Step 3: Exit agent mode (alias: /exit)

/quit

Expected Output: Agent shutdown initiated

Note

Gracefully stops Tor and restores identity if --restore-on-exit was used

Step 4: Exit agent mode (alias: /quit)

/exit

Expected Output: Agent shutdown initiated

Note

Same as /quit

Step 5: List local AI models (kodachi-ai feature)

/models

Expected Output: Local model inventory with sizes and status

Note

Requires --features kodachi-ai build

Step 6: Download AI model (kodachi-ai feature)

/models download <name>

Expected Output: Model download progress and completion

Note

Downloads ONNX or GGUF models to local cache

Step 7: Retrain NLP embeddings (kodachi-ai feature)

/train

Expected Output: Training progress and completion

Note

Retrains intent classifier from latest command data

Scenario 21: Kodachi Gateway Integration

Execute Kodachi system services via AI agent (kodachi-ai feature)

Step 1: NLP command routing to routing-switch

"switch to VPN" (in agent mode)

Expected Output: NLP detects routing intent, executes routing-switch service via gateway-core

Note

Natural language commands auto-route to appropriate Kodachi services

Step 2: NLP command routing to dns-leak

"check DNS leaks" (in agent mode)

Expected Output: Executes dns-leak service and returns results

Note

Service execution includes policy checks and risk validation

Step 3: Profile execution via profile-registry

"panic mode" (in agent mode)

Expected Output: Finds emergency profile, shows steps, executes panic sequence

Note

Workflow profiles available: panic, recovery, security-scan, network-test

Step 4: NLP routing to ip-fetch service

"check my IP" (in agent mode)

Expected Output: Fetches IP via ip-fetch and displays geolocation

Note

All service calls use recovery-engine for automatic retry on failure

Step 5: NLP routing to health-control network scan

"scan network" (in agent mode)

Expected Output: Executes health-control net-check and returns diagnostics

Note

Supports 18+ Kodachi services via kodachi-gateway-core

Scenario 22: Training & Model Management

AI model training and management (kodachi-ai feature)

Step 1: Start agent with auto-learning enabled

sudo kodachi-claw agent --provider kodachi-ai

Expected Output: Agent learns from user patterns and command sequences

Note

Learning-engine tracks patterns, sequences, and user preferences

Step 2: Manually trigger NLP retraining

/train (in agent mode)

Expected Output: Retrains intent classifier from accumulated interaction data

Note

Calls ai-trainer subprocess to rebuild embeddings

Step 3: View local model inventory

/models (in agent mode)

Expected Output: Lists ONNX classifiers, GGUF models, embeddings with sizes

Note

Shows model status: available, downloading, missing

Step 4: Refresh model catalog from sources

/models refresh (in agent mode)

Expected Output: Updates available model list from Hugging Face and local sources

Note

Checks for model updates and new releases

Scenario 23: Profile & Workflow Discovery

Discover and execute workflow profiles (kodachi-ai feature)

Step 1: Profile-based workflow execution

"run security scan" (in agent mode)

Expected Output: Finds security-scan profile (92+ profiles available), shows steps, executes sequence

Note

Profiles include: security-scan, network-test, panic-mode, recovery-workflow

Step 2: Emergency profile execution

"emergency shutdown" (in agent mode)

Expected Output: Executes panic-mode profile: kill network, wipe RAM, shutdown

Note

High-risk profiles require confirmation before execution

Step 3: Recovery profile execution

"network recovery" (in agent mode)

Expected Output: Executes recovery-workflow: check connectivity, reset interfaces, restore DNS

Note

Recovery profiles use recovery-engine for smart retry and correlation

Scenario 24: Advanced Skip Controls

Fine-grained control over startup phase skipping

Step 1: Skip MAC randomization only

sudo kodachi-claw --skip-mac agent

Expected Output: Agent starts with original MAC, hostname and timezone still randomized

Note

Useful when MAC change breaks network connectivity

Step 2: Skip hostname randomization only

sudo kodachi-claw --skip-hostname agent

Expected Output: Agent starts with original hostname, MAC and timezone still randomized

Note

Useful for preserving network identifiers

Step 3: Skip all identity randomization (MAC, hostname, timezone)

sudo kodachi-claw --skip-identity agent

Expected Output: Agent starts with original identity, Tor still active

Note

Tor routing active but no identity spoofing

Step 4: Skip Tor bootstrap only

sudo kodachi-claw --skip-tor agent

Expected Output: Agent starts without Tor, identity still randomized

Note

Identity spoofing active but no Tor routing (local testing)

Step 5: Skip all anonymity and security phases

sudo kodachi-claw --skip-all agent

Expected Output: Agent starts immediately with no protection

Note

WARNING: No anonymity, no Tor, no identity changes. Local testing ONLY

Step 6: Combine multiple skip flags

sudo kodachi-claw --skip-mac --skip-hostname --skip-tor status

Expected Output: Status with only timezone changed and no Tor

Note

Skip flags are composable for precise control

Step 7: Skip verification checks

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

Expected Output: Agent starts without post-bootstrap verification

Note

Faster startup but no connectivity/integrity validation

Scenario 25: Circuit Strategy Examples

Tor circuit assignment and load balancing strategies

Step 1: Round-robin circuit assignment (default)

sudo kodachi-claw --circuit-strategy round-robin --tor-instances 10 agent

Expected Output: Each request uses next circuit in sequence (balanced load)

Note

Best for even load distribution across circuits

Step 2: Random circuit assignment

sudo kodachi-claw --circuit-strategy random --tor-instances 8 daemon

Expected Output: Each request randomly selects a circuit

Note

Best for unpredictable traffic patterns

Step 3: Least-used circuit assignment

sudo kodachi-claw --circuit-strategy least-used --tor-instances 12 daemon

Expected Output: Each request uses circuit with lowest current load

Note

Best for uneven request sizes or long-running requests

Step 4: Sticky circuit assignment (per tool/channel)

sudo kodachi-claw --circuit-strategy sticky --tor-instances 6 agent

Expected Output: Each tool/channel always uses same dedicated circuit

Note

Best for maintaining consistent exit IPs per service

Scenario 26: Tor Mode Examples

Different Tor runtime modes and instance configurations

Step 1: Multi-circuit mode with single instance

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

Expected Output: Single Arti instance, all requests through one circuit

Note

Minimum resource mode, no circuit isolation

Step 2: Multi-circuit mode with 20 instances

sudo kodachi-claw --mode multi-circuit --tor-instances 20 daemon

Expected Output: 20 parallel Arti instances, maximum circuit diversity

Note

Maximum anonymity but high memory usage (each instance ~50MB)

Step 3: Single mode (explicit)

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

Expected Output: Single Arti instance, optimized for low-resource

Note

Equivalent to --mode multi-circuit --tor-instances 1

Step 4: Namespace isolation via oniux

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

Expected Output: Full network namespace isolation, embedded Tor

Note

Requires root or CAP_NET_ADMIN. Strongest isolation

Scenario 27: Recovery Examples

Internet connectivity recovery and troubleshooting

Step 1: Check and auto-recover internet

sudo kodachi-claw recover-internet

Expected Output: Connectivity check, recovery if needed via health-control

Note

Non-destructive check first, recovery only if needed

Step 2: Force immediate recovery

sudo kodachi-claw recover-internet --force

Expected Output: Skips check, immediately runs health-control recover-internet

Note

Use when connectivity check itself is failing

Step 3: Recovery with JSON output

sudo kodachi-claw --json recover-internet

Expected Output: JSON envelope with connectivity status, recovery actions, results

Note

Parseable output for automation and monitoring

Step 4: Agent with automatic recovery

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

Expected Output: Agent checks connectivity after MAC change and during shutdown

Note

Auto-recovers network if broken by identity changes

Step 5: Auto-recovery with identity restoration

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

Expected Output: Recovery after MAC change and during shutdown + identity restore

Note

Ensures connectivity restored before and after session

Command Examples (Raw)

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

Tor Instance Control

Control all Tor instances directly from kodachi-claw

List all known Tor instances

sudo kodachi-claw tor list-instances

Expected Output: Table of instance tags and status

List instances with current Tor exit IP

sudo kodachi-claw tor list-instances-with-ip

Expected Output: Instance table with live Tor IP addresses

Start every Tor instance

sudo kodachi-claw tor start-all-instances

Expected Output: All configured Tor instances started

Stop every Tor instance

sudo kodachi-claw tor stop-all-instances

Expected Output: All configured Tor instances stopped

Delete all non-default Tor instances

sudo kodachi-claw tor delete-all-instances

Expected Output: Custom Tor instances deleted

Delete all instances including default

sudo kodachi-claw tor delete-all-instances-with-default

Expected Output: All Tor instances deleted, including default

Note

Use when you want a full Tor instance reset

Automation-friendly Tor instance inventory

sudo kodachi-claw --json-pretty tor list-instances-with-ip

Expected Output: JSON envelope with instance and IP details

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 agent --provider groq --message "summarize this"

Expected Output: Agent response generated with Groq LPU inference

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

Local AI (kodachi-ai)

Run with local AI models — no API key required. Build with: cargo build --features kodachi-ai

Local AI agent (auto-detects ONNX/GGUF models)

sudo kodachi-claw agent --provider kodachi-ai

Expected Output: 🦀 Kodachi Claw Interactive Mode (local: ONNX + Qwen 3B)

Note

No API key needed. Auto-detects: Claude CLI > Mistral.rs > Local LLM > ONNX > TF-IDF

NLP-routed command execution

sudo kodachi-claw agent --provider kodachi-ai --message "switch to Tor"

Expected Output: NLP classifies intent, matches kodachi service commands, executes via gateway-core

Note

High-confidence NLP matches bypass the AI model for instant command routing

Onboard with local AI (zero API keys)

kodachi-claw onboard --provider kodachi-ai

Expected Output: Config created with kodachi-ai provider — fully offline capable

Note

No network needed for AI inference. Tor still used for anonymity

List available local AI models (interactive command)

/models

Expected Output: Model list: all-MiniLM-L6-v2.onnx (90MB), kodachi-intent-classifier.onnx (67MB), Qwen2.5-3B (2.1GB)

Note

Run inside agent interactive mode. Calls ai-trainer subprocess

Download a GGUF model for local inference (interactive command)

/models download Qwen2.5-3B

Expected Output: Downloading Qwen2.5-3B... done

Note

Run inside agent interactive mode. Downloads to models directory

Retrain NLP embeddings from latest command data (interactive command)

/train

Expected Output: Training embeddings... 458 commands processed, model saved

Note

Run inside agent interactive mode. Calls ai-trainer subprocess

Force specific AI tier (ONNX)

sudo kodachi-claw agent --provider kodachi-ai --tier onnx

Expected Output: Agent using ONNX classifier model only

Note

Available tiers: onnx, mistral, genai, tfidf. Auto-fallback if unavailable

Force TF-IDF fallback (no neural models)

sudo kodachi-claw agent --provider kodachi-ai --tier tfidf

Expected Output: Agent using TF-IDF keyword matching only

Note

Fastest but lowest accuracy. Useful for low-resource environments

Interactive Mode Commands

Slash commands available inside agent interactive mode

Show available interactive commands

/help

Expected Output: List of all slash commands with descriptions

Note

Run inside agent mode prompt

Clear conversation history

/clear

Expected Output: Conversation history cleared

Note

Resets context for new conversation thread

Exit agent mode (alias: /exit)

/quit

Expected Output: Agent shutdown initiated

Note

Gracefully stops Tor and restores identity if --restore-on-exit was used

Exit agent mode (alias: /quit)

/exit

Expected Output: Agent shutdown initiated

Note

Same as /quit

List local AI models (kodachi-ai feature)

/models

Expected Output: Local model inventory with sizes and status

Note

Requires --features kodachi-ai build

Download AI model (kodachi-ai feature)

/models download <name>

Expected Output: Model download progress and completion

Note

Downloads ONNX or GGUF models to local cache

Retrain NLP embeddings (kodachi-ai feature)

/train

Expected Output: Training progress and completion

Note

Retrains intent classifier from latest command data

Kodachi Gateway Integration

Execute Kodachi system services via AI agent (kodachi-ai feature)

NLP command routing to routing-switch

"switch to VPN" (in agent mode)

Expected Output: NLP detects routing intent, executes routing-switch service via gateway-core

Note

Natural language commands auto-route to appropriate Kodachi services

NLP command routing to dns-leak

"check DNS leaks" (in agent mode)

Expected Output: Executes dns-leak service and returns results

Note

Service execution includes policy checks and risk validation

Profile execution via profile-registry

"panic mode" (in agent mode)

Expected Output: Finds emergency profile, shows steps, executes panic sequence

Note

Workflow profiles available: panic, recovery, security-scan, network-test

NLP routing to ip-fetch service

"check my IP" (in agent mode)

Expected Output: Fetches IP via ip-fetch and displays geolocation

Note

All service calls use recovery-engine for automatic retry on failure

NLP routing to health-control network scan

"scan network" (in agent mode)

Expected Output: Executes health-control net-check and returns diagnostics

Note

Supports 18+ Kodachi services via kodachi-gateway-core

Training & Model Management

AI model training and management (kodachi-ai feature)

Start agent with auto-learning enabled

sudo kodachi-claw agent --provider kodachi-ai

Expected Output: Agent learns from user patterns and command sequences

Note

Learning-engine tracks patterns, sequences, and user preferences

Manually trigger NLP retraining

/train (in agent mode)

Expected Output: Retrains intent classifier from accumulated interaction data

Note

Calls ai-trainer subprocess to rebuild embeddings

View local model inventory

/models (in agent mode)

Expected Output: Lists ONNX classifiers, GGUF models, embeddings with sizes

Note

Shows model status: available, downloading, missing

Refresh model catalog from sources

/models refresh (in agent mode)

Expected Output: Updates available model list from Hugging Face and local sources

Note

Checks for model updates and new releases

Profile & Workflow Discovery

Discover and execute workflow profiles (kodachi-ai feature)

Profile-based workflow execution

"run security scan" (in agent mode)

Expected Output: Finds security-scan profile (92+ profiles available), shows steps, executes sequence

Note

Profiles include: security-scan, network-test, panic-mode, recovery-workflow

Emergency profile execution

"emergency shutdown" (in agent mode)

Expected Output: Executes panic-mode profile: kill network, wipe RAM, shutdown

Note

High-risk profiles require confirmation before execution

Recovery profile execution

"network recovery" (in agent mode)

Expected Output: Executes recovery-workflow: check connectivity, reset interfaces, restore DNS

Note

Recovery profiles use recovery-engine for smart retry and correlation

Advanced Skip Controls

Fine-grained control over startup phase skipping

Skip MAC randomization only

sudo kodachi-claw --skip-mac agent

Expected Output: Agent starts with original MAC, hostname and timezone still randomized

Note

Useful when MAC change breaks network connectivity

Skip hostname randomization only

sudo kodachi-claw --skip-hostname agent

Expected Output: Agent starts with original hostname, MAC and timezone still randomized

Note

Useful for preserving network identifiers

Skip all identity randomization (MAC, hostname, timezone)

sudo kodachi-claw --skip-identity agent

Expected Output: Agent starts with original identity, Tor still active

Note

Tor routing active but no identity spoofing

Skip Tor bootstrap only

sudo kodachi-claw --skip-tor agent

Expected Output: Agent starts without Tor, identity still randomized

Note

Identity spoofing active but no Tor routing (local testing)

Skip all anonymity and security phases

sudo kodachi-claw --skip-all agent

Expected Output: Agent starts immediately with no protection

Note

WARNING: No anonymity, no Tor, no identity changes. Local testing ONLY

Combine multiple skip flags

sudo kodachi-claw --skip-mac --skip-hostname --skip-tor status

Expected Output: Status with only timezone changed and no Tor

Note

Skip flags are composable for precise control

Skip verification checks

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

Expected Output: Agent starts without post-bootstrap verification

Note

Faster startup but no connectivity/integrity validation

Circuit Strategy Examples

Tor circuit assignment and load balancing strategies

Round-robin circuit assignment (default)

sudo kodachi-claw --circuit-strategy round-robin --tor-instances 10 agent

Expected Output: Each request uses next circuit in sequence (balanced load)

Note

Best for even load distribution across circuits

Random circuit assignment

sudo kodachi-claw --circuit-strategy random --tor-instances 8 daemon

Expected Output: Each request randomly selects a circuit

Note

Best for unpredictable traffic patterns

Least-used circuit assignment

sudo kodachi-claw --circuit-strategy least-used --tor-instances 12 daemon

Expected Output: Each request uses circuit with lowest current load

Note

Best for uneven request sizes or long-running requests

Sticky circuit assignment (per tool/channel)

sudo kodachi-claw --circuit-strategy sticky --tor-instances 6 agent

Expected Output: Each tool/channel always uses same dedicated circuit

Note

Best for maintaining consistent exit IPs per service

Tor Mode Examples

Different Tor runtime modes and instance configurations

Multi-circuit mode with single instance

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

Expected Output: Single Arti instance, all requests through one circuit

Note

Minimum resource mode, no circuit isolation

Multi-circuit mode with 20 instances

sudo kodachi-claw --mode multi-circuit --tor-instances 20 daemon

Expected Output: 20 parallel Arti instances, maximum circuit diversity

Note

Maximum anonymity but high memory usage (each instance ~50MB)

Single mode (explicit)

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

Expected Output: Single Arti instance, optimized for low-resource

Note

Equivalent to --mode multi-circuit --tor-instances 1

Namespace isolation via oniux

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

Expected Output: Full network namespace isolation, embedded Tor

Note

Requires root or CAP_NET_ADMIN. Strongest isolation

Recovery Examples

Internet connectivity recovery and troubleshooting

Check and auto-recover internet

sudo kodachi-claw recover-internet

Expected Output: Connectivity check, recovery if needed via health-control

Note

Non-destructive check first, recovery only if needed

Force immediate recovery

sudo kodachi-claw recover-internet --force

Expected Output: Skips check, immediately runs health-control recover-internet

Note

Use when connectivity check itself is failing

Recovery with JSON output

sudo kodachi-claw --json recover-internet

Expected Output: JSON envelope with connectivity status, recovery actions, results

Note

Parseable output for automation and monitoring

Agent with automatic recovery

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

Expected Output: Agent checks connectivity after MAC change and during shutdown

Note

Auto-recovers network if broken by identity changes

Auto-recovery with identity restoration

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

Expected Output: Recovery after MAC change and during shutdown + identity restore

Note

Ensures connectivity restored before and after session

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

kodachi-claw

Kodachi hardened AI runtime with embedded anonymity controls

File Information

SHA256 Checksum

Features

Security Features

System Requirements

Global Options

Commands

Commands

onboard

agent

gateway

daemon

service

tor

doctor

status

cron

models

providers

channel

integrations

skills

migrate

auth

hardware

peripheral

recover-internet

help

Operational Scenarios

Scenario 1: AI Agent

Step 1: Interactive session with full anonymity

Step 2: Single message mode

Step 3: Specific provider/model

Step 4: Local offline model

Step 5: Low temperature for deterministic output

Step 6: Hardware peripheral attached

Step 7: Use installed Claude Code CLI (no API key)

Scenario 2: Daemon & Gateway

Step 1: Full daemon with all channels

Step 2: Custom gateway port

Step 3: Bind to all interfaces

Step 4: Gateway-only (webhook/WebSocket)

Step 5: Install as systemd service

Scenario 3: Setup & Onboarding

Step 1: Full wizard (9 steps)

Step 2: Quick setup

Step 3: Quick setup with memory backend

Step 4: Quick setup with Claude Code CLI (no API key)

Step 5: Reconfigure channels only

Step 6: Bind Telegram identity

Scenario 4: Status & Diagnostics

Step 1: Full status including MAC, hostname, timezone, IP, auth

Step 2: Basic status without security/identity info

Step 3: JSON status for automation

Step 4: Run health diagnostics

Step 5: Probe model availability

Scenario 5: Scheduled Tasks

Step 1: List all scheduled tasks

Step 2: Run every 6 hours

Step 3: Weekly with timezone

Step 4: One-shot at specific time

Step 5: Every 5 minutes

Step 6: One-shot after 30 minutes

Step 7: Pause/resume tasks

Scenario 6: Models & Providers

Step 1: Refresh model catalog from default provider

Step 2: Force refresh from specific provider

Step 3: List all 12+ supported AI providers

Step 4: Check cached model availability

Scenario 7: Channel Management

Step 1: List configured channels

Step 2: Start all configured channels

Step 3: Health check all channels

Step 4: Add Telegram channel

Step 5: Remove a channel

Step 6: Bind Telegram user ID to allowlist

Scenario 8: Authentication

Step 1: OAuth login

`onboard`

`agent`

`gateway`

`daemon`

`service`

`tor`

`doctor`

`status`

`cron`

`models`

`providers`

`channel`

`integrations`

`skills`

`migrate`

`auth`

`hardware`

`peripheral`

`recover-internet`

`help`