AI Gateway (ai-gateway), Workflow Guide
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | ai-gateway |
| Version | 9.8.4 |
| Build Date | REDACTED-BUILD-TIME |
| Rust Version | 1.82.0 |
| File Size | 5.0MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | AI & Intelligence |
| Description | Unified AI gateway for command catalog, policy firewall, and safe execution |
| JSON Data | View Raw JSON |
SHA256 Checksum
What ai-gateway Does
ai-gateway is the machine-facing command API for all Kodachi services. While ai-cmd translates natural language into commands for humans, ai-gateway provides the structured execution contract that AI agents use to discover, validate, and safely execute Kodachi commands.
Any agent, OpenClaw, Claude Code, GPT, Gemini, Open Interpreter, talks to the same gateway API. One contract, every agent.
Key Capabilities
| Feature | Description |
|---|---|
| Embedded Command Catalog | 800+ commands from 15+ services, indexed at build time |
| Hybrid Search Engine | TF-IDF cosine similarity + substring matching across all services |
| Three-Tier Risk Classification | Passive (read-only), Active (system-changing), Dangerous (destructive) |
| Policy Firewall | Allowlist enforcement, workspace confinement, path validation |
| Safe Execution | Dry-run validation, JSON arguments, configurable timeouts |
| Per-Agent Identity | Token-based authentication, rate limiting, audit trail |
| Approval Tickets | Human-issued time-limited authorization for dangerous operations |
| Failure Cooldown | Prevents cascading degradation from repeated failures |
| Multiple Output Formats | --json, --json-pretty, --json-human for all commands |
Verified Agent IDs
anonymous, nullclaw, openclaw, picoclaw, nanoclaw, claude-code, gpt, gemini, open-interpreter
Scenario 1: Service Discovery, Find Available Commands
Explore all Kodachi services and their commands through the gateway catalog.
# Step 1: List all services with their commands
ai-gateway list --json
# Step 2: List commands for a specific service
ai-gateway list --service tor-switch --json
# Step 3: List health-control commands in text format
ai-gateway list --service health-control
# Step 4: Get full specification for a service
ai-gateway help tor-switch --json
# Step 5: Get detailed help for a specific command
ai-gateway help health-control security-status --json
# Step 6: Pretty-printed help for readability
ai-gateway help ip-fetch --json-pretty
Cross-binary workflow: ai-gateway discovery feeds ai-cmd and external agents
Why this matters: Agents query the gateway catalog to understand what commands exist, what parameters they accept, and what risks they carry, before executing anything.
Scenario 2: Intelligent Search, Find the Right Command
Use TF-IDF + substring hybrid search to find commands across all services by natural language description.
# Step 1: Search for Tor-related commands
ai-gateway search "tor exit node" --json
# Step 2: Search with limited results
ai-gateway search "dns leak" --limit 5 --json
# Step 3: Search in text format
ai-gateway search "network check"
# Step 4: Find emergency/panic commands
ai-gateway search "panic" --json
# Step 5: Extract machine invocation field from search result
ai-gateway search "check tor status" --limit 1 --json | jq '.data.results[0].invocation'
# Step 6: Get capability hints for planning engines
ai-gateway help tor-switch tor-status --json | jq '.data.needs_root,.data.offline_safe,.data.network_touching,.data.creates_files'
Cross-binary workflow: ai-gateway search + ai-cmd + external agents
Why this matters: Search results include machine invocation hints (invocation.service, invocation.command) that agents use to construct deterministic execution commands, no guessing, no hallucination.
Scenario 3: Safe Command Execution, Validate Before You Run
The gateway enforces a two-step pattern: dry-run validation first, live execution second.
Step 1: Dry-Run Validation (Always Safe)
# Preview a passive command without executing
ai-gateway run tor-switch --command tor-status --dry-run --json
# Preview with custom timeout
ai-gateway run dns-leak --command test --dry-run --timeout 60 --json
# Preview ip-fetch (safe in offline environments)
ai-gateway run ip-fetch --command fetch --dry-run --json
Step 2: Live Execution
# Execute passive command (no env var needed)
ai-gateway run tor-switch --command tor-status --json
# Active command with JSON arguments and explicit confirmation
ai-gateway run tor-switch --command set-exit-node --args-json '{"country":"de"}' --confirm --json
Step 3: Dangerous Commands (Requires Env Var + Confirmation)
# Dangerous command dry-run (always allowed)
ai-gateway run health-control --command wipe-logs --dry-run --json
# Dangerous command live execution (requires KODACHI_PENTEST_MODE)
KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --confirm "I understand" --json
Why this matters: The three-tier risk system (Passive/Active/Dangerous) prevents agents from accidentally executing destructive operations. Passive commands run freely, active commands need confirmation, dangerous commands need both an environment variable and explicit confirmation.
Scenario 4: Safety Policy, Understand Risk Tiers
View and manage the policy firewall that gates all command execution.
# Step 1: Show current safety policy
ai-gateway policy show --json
# Step 2: Pretty-printed policy for review
ai-gateway policy show --json-pretty
# Step 3: Understand risk tiers
# Passive, read-only operations (status, info, list)
# Active, system-changing operations (set, enable, disable)
# Dangerous, destructive operations (wipe, panic, block-internet)
Risk Tier Enforcement
| Tier | Requirements | Examples |
|---|---|---|
| Passive | None | tor-status, net-check, ip-fetch fetch |
| Active | --confirm |
set-exit-node, dns-switch switch |
| Dangerous | KODACHI_PENTEST_MODE=true + --confirm |
wipe-logs, panic-hard, block-internet |
Why this matters: The policy firewall is the safety net between AI agents and destructive system operations. Even if an agent hallucinates a dangerous command, the gateway blocks it.
Scenario 5: AI Agent Integration, One Contract, Every Agent
ai-gateway standardizes execution for all AI agents through a single gateway contract.
Step 1: Agent Finds a Command
# AI agent searches for the best matching command
ai-gateway search "check tor status" --limit 1 --json | jq '.data.results[0]'
Step 2: Agent Validates Before Executing
Step 3: Agent Executes
Step 4: External Agent Templates
# OpenClaw integration
KODACHI_ALLOW_ALL=true ai-gateway run openclaw --command status --dry-run --json
# PicoClaw integration
KODACHI_ALLOW_ALL=true ai-gateway run picoclaw --command status --dry-run --json
# NullClaw integration
KODACHI_ALLOW_ALL=true ai-gateway run nullclaw --command status --dry-run --json
Trusted Batch Mode
# Execute multiple commands in a single batch request
KODACHI_TRUSTED_BATCH_MODE=true \
KODACHI_AGENT_TOKEN_NULLCLAW=your_token \
ai-gateway run --agent-id nullclaw --agent-token your_token \
--batch-json '[{"service":"tor-switch","command":"tor-status","dry_run":true}]' --json
Cross-binary workflow: ai-gateway + openclaw + picoclaw + nullclaw
Why this matters: Every agent gets the same JSON execution contract. Whether it's a local agent or GPT calling from the cloud, the gateway API is identical.
Scenario 6: Agent Security, Identity and Approval Workflow
Verify agent identity, discover capabilities, and issue time-limited approval tickets for dangerous operations.
Step 1: Discover Agent Capabilities
# What is nullclaw allowed to do?
ai-gateway capabilities --agent-id nullclaw --agent-token $KODACHI_AGENT_TOKEN_NULLCLAW --json
# What is claude-code allowed to do?
ai-gateway capabilities --agent-id claude-code --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json
# What is GPT allowed to do?
ai-gateway capabilities --agent-id gpt --agent-token $KODACHI_AGENT_TOKEN_GPT --json
Step 2: Issue Approval Ticket for Dangerous Operation
# Human issues a time-limited ticket (600 seconds = 10 minutes)
ai-gateway approve issue health-control block-internet \
--agent-id nullclaw --ttl 600 --json | jq -r '.data.ticket'
Step 3: Agent Executes with Identity + Ticket
# Agent uses identity + approval ticket to execute dangerous command
ai-gateway run health-control --command block-internet \
--agent-id nullclaw \
--agent-token $KODACHI_AGENT_TOKEN_NULLCLAW \
--approval-ticket "$TICKET" --json
Approval Ticket Security
Without a valid ticket, execution of dangerous commands returns requires_approval. Tickets are time-limited and single-use. Set KODACHI_GATEWAY_APPROVAL_SECRET for stable verification across sessions.
Cross-binary workflow: ai-gateway + any verified agent
Why this matters: The approval ticket workflow puts a human in the loop for dangerous operations. An agent can discover and validate commands autonomously, but destructive actions require explicit human authorization.
Scenario 7: System Administration, Index and Health
Maintain the gateway's command index and verify binary health.
# Step 1: Rebuild the search index
ai-gateway index rebuild --json
# Step 2: Check health of all registered binaries
ai-gateway doctor --json
# Step 3: Health check in text format
ai-gateway doctor
# Step 4: Show version and program info
ai-gateway --version
ai-gateway --info --json
Cross-binary workflow: ai-gateway doctor checks all Kodachi binaries
When to run: After installing new binaries, after system updates, or when search results seem stale.
Scenario 8: Automated Workflows, ai-gateway + ai-scheduler
Combine ai-gateway with ai-scheduler for automated, policy-gated command execution.
# Schedule periodic Tor status checks through the gateway
ai-scheduler add --name "gateway-tor-check" \
--command "ai-gateway run tor-switch --command tor-status --json" \
--cron "*/30 * * * *"
# Schedule daily DNS leak test
ai-scheduler add --name "gateway-dns-test" \
--command "ai-gateway run dns-leak --command test --json" \
--cron "0 6 * * *"
# Schedule daily gateway health check
ai-scheduler add --name "gateway-doctor" \
--command "ai-gateway doctor --json" \
--cron "0 1 * * *"
# Verify all scheduled tasks
ai-scheduler list
Cross-binary workflow: ai-gateway + ai-scheduler
Why this matters: By routing scheduled commands through ai-gateway, all executions go through the policy firewall, even automated ones. The risk tier system protects against misconfigured cron jobs.
Related Workflows
- AI Overview, Full AI architecture, KAICS system, and gateway layer details
- AI Overview: Gateway Layer, Verified command patterns and trusted batch mode
- ai-cmd Guide, Natural language command execution (delegates through ai-gateway)
- ai-scheduler Guide, Automate gateway commands on a schedule
- Full CLI Reference: ai-gateway commands
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| "Unknown service" error | Binary not in allowlist | Check ai-gateway policy show --json for allowed services |
| Search returns no results | Index stale or empty | Rebuild: ai-gateway index rebuild --json |
| "Dangerous command blocked" | Missing env var or confirmation | Set KODACHI_PENTEST_MODE=true and add --confirm |
| "requires_approval" response | Dangerous operation without ticket | Issue ticket: ai-gateway approve issue <service> <command> --agent-id <id> --ttl 600 --json |
| Agent token rejected | Invalid or expired token | Verify token env var: KODACHI_AGENT_TOKEN_<AGENT_ID> |
| Doctor shows binary missing | Binary not installed or not in PATH | Install binary or verify path with which <binary> |
| Timeout on execution | Default 30s too short | Use --timeout 60 or set KODACHI_TOOL_TIMEOUT_MS env var |