AI Gateway (ai-gateway) — Workflow Guide
File Information
| Property | Value |
|---|---|
| Binary Name | ai-gateway |
| Version | 9.0.1 |
| File Size | 4.3MB |
| 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 — kodachi-claw, ZeroClaw, 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, kodachi-claw, nullclaw, openclaw, picoclaw, nanoclaw, claude-code, gpt, gemini, open-interpreter
Agent ID Aliases
zeroclaw is accepted as an alias and normalizes to kodachi-claw internally. Both names work in --agent-id flags.
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 set-server |
| 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
# Passive command (no env required)
ai-gateway run tor-switch --command tor-status --json
# kodachi-claw integration path
ai-gateway run kodachi-claw --command status --dry-run --json
ai-gateway run kodachi-claw --command status --json
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_ZEROCLAW=your_token \
ai-gateway run --agent-id zeroclaw --agent-token your_token \
--batch-json '[{"service":"tor-switch","command":"tor-status","dry_run":true}]' --json
Cross-binary workflow: ai-gateway + kodachi-claw + zeroclaw + openclaw + picoclaw + nullclaw
Why this matters: Every agent gets the same JSON execution contract. Whether it's kodachi-claw running through Tor 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 kodachi-claw allowed to do?
ai-gateway capabilities --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --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 kodachi-claw --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 kodachi-claw \
--agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW \
--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 + kodachi-claw (or 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
- kodachi-claw Guide — Anonymous AI agent runtime that integrates with ai-gateway
- 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 |