AI SUITE GUIDE

ai-gateway Guide

The machine-facing command API for every Kodachi service. It gives AI agents one structured contract to discover, validate, and safely execute commands, with a three-tier risk policy and per-agent identity.

Agent contract Policy firewall Dry-run first 9 agent profiles

ai-gateway at a glance

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, NullClaw, AgentZero, OpenClaw, Claude Code, GPT, Gemini, Open Interpreter, talks to the same gateway API: one contract, every agent.

Version 9.8.4 5.0 MB binary Rust 1.82.0 9 verified agents

Reference and verification

This is a scenario-first guide: operational workflows, real run order, and troubleshooting. For the full autogenerated command and flag catalog, use the ai-gateway CLI Reference, or read the raw signer JSON.

SHA256 (v9.8.4): 4c5611130d9230d187d6c5f60aa1a6e259de9dc189c406edc733980a51d6875b

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

The gateway ships nine verified agent profiles. Each authenticated agent presents a token and gets its own rate limit and capability set. Callers with no identity fall back to the built-in anonymous profile (no token, tightest limits), so anonymous is the unauthenticated default, not one of the nine peers.

Agent ID	Profile
`nullclaw`	NullClaw trusted runtime
`agentzero`	AgentZero autonomous framework
`openclaw`	OpenClaw public agent runtime
`picoclaw`	PicoClaw lightweight runtime
`nanoclaw`	NanoClaw embedded runtime
`claude-code`	Claude Code trusted agent profile
`gpt`	GPT trusted agent profile
`gemini`	Gemini trusted agent profile
`open-interpreter`	Open Interpreter trusted agent profile

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

# Dry-run validation (always safe)
ai-gateway run tor-switch --command tor-status --dry-run --json

Step 3: Agent Executes

# Passive command (no env required)
ai-gateway run tor-switch --command tor-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_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.

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