{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:40Z", "binary_name": "ai-gateway" }, "binary": { "name": "ai-gateway", "path": "/opt/kodachi/dashboard/hooks/ai-gateway", "timestamp": "2026-07-21T01:54:40Z", "file_info": { "size": 5858288, "sha256": "12f0a34133f789f27c6c09ed690a337b0d86792067b4ed2e6f60a14705f69a05" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:41.039285859Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-gateway", "version": "9.8.4", "author": "Warith Al Maawali", "description": "Unified AI gateway for command catalog, policy firewall, and safe execution", "copyright": "© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "Proprietary", "features": [ "Embedded command catalog with 568 commands from 25 services", "TF-IDF + substring hybrid search across all services", "Three-tier risk classification (Passive/Active/Dangerous)", "Policy firewall with allowlist enforcement", "Workspace confinement and path validation", "Failure cooldown to prevent cascading degradation", "Per-agent identity, rate limiting, and audit trail for executions", "Approval ticket workflow for agent-to-human authorization", "Configurable per-operation timeouts with env var override", "Full JSON/JSON-pretty/JSON-human output support" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:41.182810411Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-gateway", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:41.323460167Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-gateway", "description": "Unified AI gateway for command catalog, policy firewall, and safe execution", "usage": "ai-gateway [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Administration", "commands": [ { "name": "index", "description": "Rebuild the search index from the embedded registry", "usage": "ai-gateway index rebuild", "options": [ { "flag": "rebuild", "description": "Rebuild the TF-IDF search index over the command catalog and print the service and command counts. Run this after upgrading the hook binaries.", "required": true } ], "requires_sudo": false, "examples": [ "ai-gateway index rebuild", "ai-gateway index rebuild --json", "ai-gateway index rebuild --json-pretty" ] }, { "name": "policy", "description": "Show the current safety policy configuration", "usage": "ai-gateway policy show", "options": [ { "flag": "show", "description": "Display the policy firewall: risk-tier rules, the service allowlist, and whether KODACHI_PENTEST_MODE is currently enabled. Read-only.", "required": true } ], "requires_sudo": false, "examples": [ "ai-gateway policy show", "ai-gateway policy show --json", "ai-gateway policy show --json-pretty" ] }, { "name": "doctor", "description": "Health check that verifies all registered binaries exist and respond", "usage": "ai-gateway doctor", "options": [ { "flag": "(no command-specific options)", "description": "doctor probes every registered binary and reports whether it exists, responds, and at which version. Use the global --json, --json-pretty or --json-human to pick the output shape." } ], "requires_sudo": false, "examples": [ "ai-gateway doctor", "ai-gateway doctor --json", "ai-gateway doctor --json-pretty" ] }, { "name": "approve", "description": "Issue or verify human approval tickets for agent execution", "usage": "ai-gateway approve issue [--agent-id ] [--ttl ]\nai-gateway approve verify --ticket [--agent-id ]", "options": [ { "flag": "issue ", "description": "Issue a signed, time-limited approval ticket for one service and command (requires KODACHI_GATEWAY_APPROVAL_SECRET)", "required": true }, { "flag": "verify --ticket ", "description": "Verify a ticket against the service and command it was issued for", "required": true }, { "flag": "--agent-id ", "description": "Agent identity the ticket is bound to", "default": "anonymous" }, { "flag": "--ttl ", "description": "Ticket lifetime in seconds, 1 to 3600 (issue only)", "default": "300" } ], "requires_sudo": false, "examples": [ "ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json", "ai-gateway approve verify --ticket \"$TICKET\" health-control block-internet --agent-id kodachi-claw --json" ] } ] }, { "category": "Discovery", "commands": [ { "name": "list", "description": "List all services and their commands from the embedded registry", "usage": "ai-gateway list [--service ] [--category ]", "options": [ { "flag": "--service", "description": "Filter by service name" }, { "flag": "--category", "description": "Filter by category name" } ], "requires_sudo": false, "examples": [ "ai-gateway list", "ai-gateway list --json", "ai-gateway list --service tor-switch", "ai-gateway list --service health-control --json", "ai-gateway list --category passive" ] }, { "name": "search", "description": "Search across all services and commands using TF-IDF + substring matching", "usage": "ai-gateway search [--limit ]", "options": [ { "flag": "--limit", "description": "Maximum number of results to return", "default": "20" } ], "requires_sudo": false, "examples": [ "ai-gateway search \"tor status\"", "ai-gateway search \"dns leak\" --json", "ai-gateway search \"network check\" --limit 5", "ai-gateway search \"panic\" --json-pretty" ] }, { "name": "help", "description": "Show detailed help for a service or specific command", "usage": "ai-gateway help [command]", "options": [ { "flag": "", "description": "Service name from the embedded catalog, for example tor-switch. An --agent-id value such as zeroclaw is not a service and returns \"Service not found\".", "required": true }, { "flag": "[COMMAND]", "description": "Optional command name. Omit it for the whole service spec.", "required": false } ], "requires_sudo": false, "examples": [ "ai-gateway help tor-switch", "ai-gateway help tor-switch tor-status --json", "ai-gateway help health-control --json-pretty", "ai-gateway help dns-leak test", "ai-gateway help ip-fetch fetch --json" ] }, { "name": "capabilities", "description": "Show effective capabilities for an AI agent identity", "usage": "ai-gateway capabilities [--agent-id ] [--agent-token ]", "options": [ { "flag": "--agent-id", "description": "Agent profile (kodachi-claw/nullclaw/agentzero/openclaw/picoclaw/nanoclaw/claude-code/gpt/gemini/open-interpreter; aliases: zeroclaw, nanclaw, \"claude code\", \"open interpreter\")", "default": "anonymous" }, { "flag": "--agent-token", "description": "Optional token for authenticated agent profiles" } ], "requires_sudo": false, "examples": [ "ai-gateway capabilities --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --json", "ai-gateway capabilities --agent-id nullclaw --agent-token $KODACHI_AGENT_TOKEN_NULLCLAW", "ai-gateway capabilities --agent-id openclaw --agent-token $KODACHI_AGENT_TOKEN_OPENCLAW --json", "ai-gateway capabilities --agent-id picoclaw --agent-token $KODACHI_AGENT_TOKEN_PICOCLAW --json", "ai-gateway capabilities --agent-id nanoclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json", "ai-gateway capabilities --agent-id nanclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json", "ai-gateway capabilities --agent-id claude-code --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json", "ai-gateway capabilities --agent-id \"claude code\" --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json", "ai-gateway capabilities --agent-id gpt --agent-token $KODACHI_AGENT_TOKEN_GPT --json", "ai-gateway capabilities --agent-id gemini --agent-token $KODACHI_AGENT_TOKEN_GEMINI --json", "ai-gateway capabilities --agent-id open-interpreter --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json", "ai-gateway capabilities --agent-id \"open interpreter\" --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json", "ai-gateway capabilities --agent-id anonymous --json" ] } ] }, { "category": "Execution", "commands": [ { "name": "run", "description": "Validate and execute a binary command through the safety layer", "usage": "ai-gateway run --command [--args ...] [--args-json ] [--dry-run] [--timeout ] [--agent-id ] [--agent-token ] [--approval-ticket ] OR ai-gateway run --batch-json --agent-id --agent-token ", "options": [ { "flag": "", "description": "Service to invoke (required unless --batch-json is used)" }, { "flag": "--command ", "description": "Command to execute (required unless --batch-json is used)" }, { "flag": "--args", "description": "Command arguments (multiple)" }, { "flag": "--args-json", "description": "Command arguments as JSON object/array" }, { "flag": "--batch-json", "description": "Batch execution payload for trusted agents (JSON array, sequential mode only)" }, { "flag": "--dry-run", "description": "Validate without executing" }, { "flag": "--timeout", "description": "Execution timeout in seconds", "default": "60" }, { "flag": "--confirm", "description": "Approval token for commands requiring confirmation" }, { "flag": "--approval-ticket", "description": "Human-issued approval ticket for Active/Dangerous commands" }, { "flag": "--agent-id", "description": "Agent profile (trusted profiles require token auth)", "default": "anonymous" }, { "flag": "--agent-token", "description": "Agent auth token for token-required profiles" } ], "requires_sudo": false, "examples": [ "ai-gateway run health-control --command net-check --dry-run", "ai-gateway run ip-fetch --command fetch --dry-run --json", "ai-gateway run tor-switch --command tor-status --timeout 60 --json", "ai-gateway run tor-switch --command set-exit-node --args-json '[\"de\"]' --dry-run --json", "ai-gateway run dns-leak --command test --dry-run --json-pretty", "ai-gateway run tor-switch --command tor-status --agent-id claude-code --agent-token \"$KODACHI_AGENT_TOKEN_CLAUDE_CODE\" --dry-run --json", "KODACHI_TRUSTED_BATCH_MODE=true ai-gateway run --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --batch-json '[{\"service\":\"ip-fetch\",\"command\":\"fetch\",\"dry_run\":true},{\"service\":\"tor-switch\",\"command\":\"tor-status\",\"dry_run\":true}]' --json", "KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --args-json '{\"file\":\"results/example-to-wipe.txt\"}' --confirm \"I understand\" --dry-run --json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format ", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter ", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields ", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--offset ", "description": "Skip first N results (for pagination)" }, { "flag": "--port ", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level ", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "3": "Permission denied", "5": "File not found", "1": "General error", "2": "Invalid arguments", "0": "Success", "4": "Network error" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:41.628281649Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-gateway", "description": "Usage examples for ai-gateway", "categories": [ { "id": "0_quick_start", "title": "Quick Start", "description": "The gateway is the one safe door into every other Kodachi binary: find a command, read its spec, preview it, then run it. ai-gateway itself never needs root, but the service it launches may.", "examples": [ { "command": "ai-gateway search \"tor exit node\" --limit 5 --json", "description": "Find the command you want without knowing which service owns it", "expectedOutput": "Top 5 ranked matches, each with service, command, description and score" }, { "command": "ai-gateway help tor-switch tor-status --json", "description": "Read the full spec of a command before you invoke it", "expectedOutput": "JSON command spec with options, examples and risk tier" }, { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "Preview the invocation: policy check, no execution", "expectedOutput": "Validation result showing the resolved binary and argv that would run" }, { "command": "ai-gateway run tor-switch --command tor-status --json", "description": "Run it for real once the dry-run looks right", "expectedOutput": "The live tor-status output, wrapped in the gateway envelope", "notes": "Passive commands need no confirmation and no env var. Active commands need --confirm, and Dangerous commands additionally need KODACHI_PENTEST_MODE=true." } ] }, { "id": "1_discovery", "title": "Service Discovery", "description": "Browse the embedded catalog of every Kodachi service and command. The catalog is compiled into the binary, so list works offline and without authentication.", "examples": [ { "command": "ai-gateway list --json", "description": "List every service in the catalog with its commands", "expectedOutput": "JSON array of the registered services, each with its command list and metadata" }, { "command": "ai-gateway list --service tor-switch --json", "description": "Narrow the catalog to one service", "expectedOutput": "The tor-switch commands with descriptions and risk tiers" }, { "command": "ai-gateway list --category Discovery", "description": "Filter by command category instead of by service", "expectedOutput": "The commands whose category matches, across all services", "notes": "--category (-c) matches the category name a service assigns to its own commands, so the useful values differ per service. Run 'ai-gateway list --service ' first to see which categories that service uses." }, { "command": "ai-gateway list --service health-control", "description": "Same listing in readable text instead of JSON", "expectedOutput": "A formatted list of the health-control commands" } ] }, { "id": "2_search", "title": "Command Search", "description": "Search across all services using TF-IDF + substring hybrid search engine", "examples": [ { "command": "ai-gateway search \"tor exit node\" --json", "description": "Search for Tor exit node commands", "expectedOutput": "Ranked results with relevance scores", "notes": "Uses TF-IDF cosine similarity + substring matching" }, { "command": "ai-gateway search \"dns leak\" --limit 5 --json", "description": "Search with limited results", "expectedOutput": "Top 5 matching commands for DNS leak operations" }, { "command": "ai-gateway search \"network check\"", "description": "Search for network check commands in text format", "expectedOutput": "Numbered list of matching commands with scores" }, { "command": "ai-gateway search \"panic\" --json", "description": "Find all panic/emergency commands", "expectedOutput": "Emergency commands with Dangerous risk tier", "notes": "Dangerous commands are blocked unless pentest mode" } ] }, { "id": "3_help", "title": "Service Help", "description": "Get detailed help for any service or specific command", "examples": [ { "command": "ai-gateway help tor-switch --json", "description": "Full specification for tor-switch service", "expectedOutput": "JSON with all commands, options, examples, features, requirements" }, { "command": "ai-gateway help health-control security-status --json", "description": "Help for a specific command", "expectedOutput": "Detailed command spec with parameters and examples" }, { "command": "ai-gateway help dns-switch", "description": "Text help for dns-switch service", "expectedOutput": "Formatted help output for dns-switch" }, { "command": "ai-gateway help ip-fetch --json-pretty", "description": "Pretty-printed JSON help for ip-fetch", "expectedOutput": "Indented JSON with full service specification" } ] }, { "id": "4_execution", "title": "Safe Command Execution", "description": "Validate first, then execute when appropriate. No env var is needed for passive/active commands.", "examples": [ { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "Step 1 (validate): preview a passive command", "expectedOutput": "Validation result without actual execution", "notes": "Always use --dry-run first for safety" }, { "command": "ai-gateway run tor-switch --command tor-status --json", "description": "Step 2 (apply): execute passive command (no env needed)", "expectedOutput": "Live command execution result", "notes": "Passive commands execute without KODACHI_PENTEST_MODE" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args-json '[\"de\"]' --confirm --dry-run --json", "description": "Active command flow (no env needed): validate with explicit confirmation", "expectedOutput": "Validated active operation with parsed args-json", "notes": "For active commands, remove --dry-run to apply changes" }, { "command": "ai-gateway run dns-leak --command test --dry-run --timeout 60 --json", "description": "Dry-run DNS leak test with custom timeout", "expectedOutput": "Validation result for dns-leak test", "notes": "Timeout can be overridden with KODACHI_TOOL_TIMEOUT_MS env var" }, { "command": "ai-gateway run ip-fetch --command fetch --dry-run --json", "description": "Dry-run ip-fetch fetch command", "expectedOutput": "Validation result for ip-fetch fetch", "notes": "Dry-run keeps examples deterministic in offline/auth-restricted environments" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args-json '[\"de\"]' --dry-run --json", "description": "Pass structured JSON arguments for agent-safe invocation", "expectedOutput": "Dry-run validation with args expanded from JSON", "notes": "--args-json avoids brittle shell quoting in agent pipelines" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args de --dry-run --json", "description": "Pass plain positional arguments straight through to the service", "expectedOutput": "Dry-run validation showing the argv the service would receive, including the passed-through arguments", "notes": "--args (-a) takes any number of values and forwards them verbatim, so everything after it is consumed as an argument until the next flag. Use --args-json instead when the values could be mistaken for gateway flags." }, { "command": "ai-gateway run health-control --command net-check --agent-id claude-code --agent-token \"$KODACHI_AGENT_TOKEN_CLAUDE_CODE\" --dry-run --json", "description": "Run under an agent identity so the call is rate-limited and audited", "expectedOutput": "Dry-run validation plus the identity that was authenticated and the risk tier it is allowed to reach", "notes": "The token is read server-side from the env var KODACHI_AGENT_TOKEN_, uppercased with '-' replaced by '_'. It must be EXPORTED: if it is unset, the shell expands it to nothing and clap fails with \"a value is required\"." } ] }, { "id": "5_policy", "title": "Safety Policy", "description": "Read the policy firewall: which services are allowlisted, how commands are classified into the Passive, Active and Dangerous risk tiers, and what each tier demands before it will run.", "examples": [ { "command": "ai-gateway policy show --json", "description": "Show the active safety policy as JSON", "expectedOutput": "The risk-tier rules, the service allowlist, and whether pentest mode is currently on" }, { "command": "ai-gateway policy show", "description": "Show the same policy as readable text", "expectedOutput": "A formatted policy summary" }, { "command": "ai-gateway policy show --json-pretty", "description": "Indented policy JSON, easier to read while debugging a block", "expectedOutput": "Indented JSON with the complete policy details", "notes": "If a run was refused, this is the command that tells you why: check the command's tier and whether its service is on the allowlist." }, { "command": "KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --args-json '{\"file\":\"results/example-to-wipe.txt\"}' --confirm \"I understand\" --dry-run --json", "description": "Preview a Dangerous command: it needs the env var AND an explicit confirmation token", "expectedOutput": "Validation of the dangerous invocation, with nothing executed because of --dry-run", "notes": "KEEP --dry-run. The example target is only illustrative. Without dry-run this really does wipe the target file, and wipe-file is irreversible. KODACHI_PENTEST_MODE=true is required only for the Dangerous tier, and --confirm must be exactly \"I understand\" or dangerous::." } ] }, { "id": "6_administration", "title": "Administration and Troubleshooting", "description": "Keep the search index fresh and find out why a service will not run. These are the commands to reach for when a run fails and you do not know whether the fault is policy, the index, or a missing binary.", "examples": [ { "command": "ai-gateway index rebuild --json", "description": "Rebuild the TF-IDF search index over the command catalog", "expectedOutput": "Index statistics: how many services and commands were indexed", "notes": "Do this after upgrading the hook binaries, otherwise search still ranks against the previous catalog." }, { "command": "ai-gateway doctor --json", "description": "Probe every registered binary and report whether it is usable", "expectedOutput": "Per-binary health: whether the file exists, whether it responds, its version and its size", "notes": "This is what to run when a run failed with \"Binary not found\": doctor shows exactly which entries have no binary behind them." }, { "command": "ai-gateway doctor", "description": "Same health check as a readable table", "expectedOutput": "A table of binary names against their health status", "notes": "doctor executes each binary with a probe flag, so it is slower than the other commands here." } ] }, { "id": "7_output_formats", "title": "Output Formats and Metadata", "description": "Every command accepts the same three JSON shapes, plus the binary's own metadata flags. Pick compact JSON for scripts, pretty for reading, and human when you want it formatted like jq.", "examples": [ { "command": "ai-gateway doctor --json", "description": "Compact JSON: one line, best for piping into a script", "expectedOutput": "A single-line JSON envelope" }, { "command": "ai-gateway search \"dns leak\" --json-pretty", "description": "Indented JSON for reading a result by eye", "expectedOutput": "The same envelope, indented across multiple lines" }, { "command": "ai-gateway policy show --json-human", "description": "Formatted, jq-style JSON", "expectedOutput": "The policy envelope, highlighted and formatted for a human" }, { "command": "ai-gateway --info --json", "description": "Report what this build of the gateway can do", "expectedOutput": "JSON with the feature list, security properties and requirements" }, { "command": "ai-gateway --version", "description": "Print the gateway version", "expectedOutput": "The ai-gateway version string" } ] }, { "id": "8_ai_agent_integration", "title": "AI Agent Integration", "description": "The loop an AI agent runs: search for the command, read its spec, dry-run it, then execute under an agent identity. IMPORTANT: an agent name (kodachi-claw, nullclaw, agentzero, openclaw, picoclaw, nanoclaw, claude-code, gpt, gemini, open-interpreter) is a value for --agent-id, NOT a service you can 'run'. The service argument of 'run' must be a Kodachi binary from the catalog, such as tor-switch or ip-fetch. Use 'ai-gateway list' to see what is runnable.", "examples": [ { "command": "ai-gateway search \"check tor status\" --limit 1 --json", "description": "Step 1: the agent finds the best matching command", "expectedOutput": "The single top match, with its service, command and score", "notes": "ai-cmd delegates its execution to ai-gateway, so an agent that goes through the gateway gets the same safety checks either way." }, { "command": "ai-gateway help tor-switch tor-status --json", "description": "Step 2: the agent reads the machine-readable command spec", "expectedOutput": "The command spec: parameters, defaults, examples and risk tier", "notes": "'help' resolves the name against the embedded service catalog. An --agent-id value such as zeroclaw is not a service, so 'help zeroclaw' returns \"Service not found\"." }, { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "Step 3: the agent validates the invocation before committing to it", "expectedOutput": "Validation passes and shows exactly what would have run" }, { "command": "ai-gateway run tor-switch --command tor-status --agent-id claude-code --agent-token \"$KODACHI_AGENT_TOKEN_CLAUDE_CODE\" --json", "description": "Step 4: the agent executes under its own identity, so the call is rate-limited and audited", "expectedOutput": "The live tor-status result, plus the identity and rate limit that were applied", "notes": "Every named profile except 'anonymous' requires a token. Export KODACHI_AGENT_TOKEN_CLAUDE_CODE first: if it is unset the shell drops the word and clap fails with \"a value is required\"." }, { "command": "ai-gateway capabilities --agent-id nullclaw --agent-token \"$KODACHI_AGENT_TOKEN_NULLCLAW\" --json", "description": "Ask the gateway what a given agent identity is actually allowed to do", "expectedOutput": "The effective services, the highest risk tier allowed, and the per-minute rate limit", "notes": "This is the correct way to work with an agent name. 'run nullclaw' is not: nullclaw is an identity, and it is only a runnable service if you have separately installed a third-party binary of that name (see the External agent runtimes category)." } ] }, { "id": "8b_external_runtimes", "title": "External Agent Runtimes", "description": "Kodachi does not ship any agent runtime binary. The policy allowlist reserves three optional third-party names (kodachi-claw, nullclaw, aeroclaw) and the registry discovers them at runtime, but only if you have installed a binary of that name into the hooks directory yourself. On a stock install none of them exists, so running one fails with \"Binary not found\". Everything below assumes you installed it.", "examples": [ { "command": "ai-gateway doctor --json", "description": "Check whether an external agent runtime is actually installed", "expectedOutput": "The per-binary health report. An external runtime you have not installed simply does not appear, which is the normal state.", "notes": "Do this before you write a script against kodachi-claw, nullclaw or aeroclaw. They are optional and are not part of a stock Kodachi install." }, { "command": "ai-gateway policy show --json", "description": "Confirm which service names the policy firewall will even accept", "expectedOutput": "The allowlist, which includes the Kodachi services plus the reserved external names kodachi-claw, nullclaw and aeroclaw", "notes": "Being on the allowlist only means the policy will not refuse the name. The binary still has to exist on disk. Names such as agentzero, openclaw, picoclaw and nanoclaw are NOT on the allowlist: they exist only as --agent-id identities." }, { "command": "ai-gateway list --service kodachi-claw --json", "description": "List what an installed external runtime exposes", "expectedOutput": "The commands the runtime reported when the registry probed it, or a not-found error if it is not installed", "notes": "The registry discovers an external runtime by executing it with a probe flag under a 5 second timeout, so its command list comes from the binary itself, not from the compiled catalog." } ] }, { "id": "9_agent_security", "title": "Agent Identity, Tokens and Approval Tickets", "description": "Every execution can carry an agent identity, which decides the highest risk tier it may reach, its rate limit, and what lands in the audit trail. Valid --agent-id values: anonymous, kodachi-claw, nullclaw, agentzero, openclaw, picoclaw, nanoclaw, claude-code, gpt, gemini, open-interpreter (zeroclaw is accepted as an alias of kodachi-claw). TOKENS: every profile except anonymous requires one. The gateway reads it server-side from the env var KODACHI_AGENT_TOKEN_, uppercased with '-' turned into '_', and that variable must be EXPORTED before you run these commands. If it is unset, the shell expands $KODACHI_AGENT_TOKEN_... to nothing, the word disappears from the command line, and clap fails with \"a value is required\".", "examples": [ { "command": "export KODACHI_AGENT_TOKEN_CLAUDE_CODE=\"\"", "description": "Set the token for an agent identity, once per shell", "expectedOutput": "No output. Every later --agent-id claude-code call can now authenticate.", "notes": "The env var name is derived from the agent id: kodachi-claw becomes KODACHI_AGENT_TOKEN_KODACHI_CLAW, open-interpreter becomes KODACHI_AGENT_TOKEN_OPEN_INTERPRETER." }, { "command": "ai-gateway capabilities --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --json", "description": "Ask what a trusted agent identity is allowed to do", "expectedOutput": "Its effective services, its maximum risk tier, and its per-minute rate limit" }, { "command": "ai-gateway capabilities --agent-id anonymous --json", "description": "Show the default capabilities of an unidentified caller", "expectedOutput": "The anonymous profile: no token needed, and a lower rate limit than the named profiles", "notes": "anonymous is the only profile that needs no token, and it is the default when you omit --agent-id." }, { "command": "ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json", "description": "A human issues a time-limited ticket authorizing one agent to run one command", "expectedOutput": "A signed approval ticket string, valid for the TTL you gave", "notes": "Requires KODACHI_GATEWAY_APPROVAL_SECRET to be exported. --ttl is in seconds and must be 1 to 3600 (default 300). The ticket is bound to that exact service, command and agent id." }, { "command": "ai-gateway approve verify --ticket \"$TICKET\" health-control block-internet --agent-id kodachi-claw --json", "description": "Check a ticket is genuine and still valid before relying on it", "expectedOutput": "Whether the ticket verifies against this service, command and agent, and when it expires", "notes": "The service and command are positional and must match the ones the ticket was issued for, or verification fails." }, { "command": "ai-gateway run health-control --command block-internet --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --approval-ticket \"$TICKET\" --dry-run --json", "description": "The agent presents its identity and its ticket to run a gated command", "expectedOutput": "Execution gated by the identity policy, the rate limit and ticket verification. With --dry-run, nothing runs.", "notes": "block-internet cuts all network access on this machine. Drop --dry-run only when you mean it. Without a valid ticket the gateway refuses and returns requires_approval." }, { "command": "KODACHI_TRUSTED_BATCH_MODE=true ai-gateway run --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --batch-json '[{\"service\":\"ip-fetch\",\"command\":\"fetch\",\"dry_run\":true},{\"service\":\"tor-switch\",\"command\":\"tor-status\",\"dry_run\":true}]' --json", "description": "Run several invocations in one call, sequentially, as a trusted agent", "expectedOutput": "One result per entry in the array, in order, each with its own policy verdict", "notes": "Batch mode needs three things at once: KODACHI_TRUSTED_BATCH_MODE=true, an authenticated agent, and a profile that requires a token. anonymous can never batch. When --batch-json is used, the service argument and --command are supplied inside the JSON instead of on the command line. Each entry may set its own dry_run." } ] } ], "quickReference": [ "ai-gateway --help", "ai-gateway --version", "ai-gateway --info --json", "ai-gateway --examples", "ai-gateway list --json", "ai-gateway search \"tor exit node\" --limit 5 --json", "ai-gateway help tor-switch tor-status --json", "ai-gateway run tor-switch --command tor-status --dry-run --json", "ai-gateway policy show --json", "ai-gateway doctor --json" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } } }