Binary reference

ai-gateway

Unified AI gateway for command catalog, policy firewall, and safe execution

Version9.8.4Size5.2MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	ai-gateway
Version	9.8.4
Build Date	Not disclosed
Rust Version	1.82.0
File Size	5.2MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	Unified AI gateway for command catalog, policy firewall, and safe execution
Git Commit	unknown
Metadata Generated	2026-07-11T18:16:26Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

65014e896211db926eaf0058a1492e0fb2049c7d2f1ff63c0d2c9d807db83cd9

Features

#	Feature
1	Embedded command catalog with 800+ commands from 15+ services
2	TF-IDF + substring hybrid search across all services
3	Three-tier risk classification (Passive/Active/Dangerous)
4	Policy firewall with allowlist enforcement
5	Workspace confinement and path validation
6	Failure cooldown to prevent cascading degradation
7	Per-agent identity, rate limiting, and audit trail for executions
8	Approval ticket workflow for agent-to-human authorization
9	Configurable per-operation timeouts with env var override
10	Full JSON/JSON-pretty/JSON-human output support

Security Features

Feature	Description
Input Validation	Argument parsing via clap; per-command validation is the consumer's responsibility
Rate Limiting	Not provided by cli-core
Authentication	Not provided by cli-core (see online-auth)
Encryption	Not provided by cli-core

System Requirements

Requirement	Value
OS	Linux (Debian-based)
Privileges	root/sudo for system operations
Dependencies	OpenSSL, libcurl

Global Options

Flag	Description
`-h, --help`	Print help information
`-v, --version`	Print version information
`-n, --info`	Display detailed information
`-e, --examples`	Show usage examples
`--json`	Output in JSON format
`-o, --output-format <FORMAT>`	Force output format (text\|json)
`--json-pretty`	Pretty-print JSON output with indentation
`--json-human`	Enhanced JSON output with improved formatting (like jq)
`--fields <FIELD_LIST>`	Select specific fields to include in output (comma-separated)
`--limit <NUMBER>`	Limit number of results returned
`--offset <NUMBER>`	Skip first N results (for pagination)
`-d, --work-dir <PATH>`	Working directory (defaults to auto-detected base directory)
`--port <PORT>`	Set custom port number (1024-65535)
`--log-level <LEVEL>`	Set log level (error\|warn\|info\|debug)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--config <FILE>`	Use custom configuration file
`--timeout <SECS>`	Set operation timeout in seconds (optional; no default applied)
`--retry <COUNT>`	Retry attempts (optional; no default applied)

Commands

Administration

`index`

Rebuild the search index from the embedded registry

Usage:

ai-gateway index rebuild

Examples:

ai-gateway index rebuild

ai-gateway index rebuild --json

ai-gateway index rebuild --json-pretty

`policy`

Show the current safety policy configuration

Usage:

ai-gateway policy show

Examples:

ai-gateway policy show

ai-gateway policy show --json

ai-gateway policy show --json-pretty

`doctor`

Health check that verifies all registered binaries exist and respond

Usage:

ai-gateway doctor

Examples:

ai-gateway doctor

ai-gateway doctor --json

ai-gateway doctor --json-pretty

`approve`

Issue or verify human approval tickets for agent execution

Usage:

ai-gateway approve issue <service> <command> [--agent-id <id>] [--ttl <secs>]
ai-gateway approve verify --ticket <ticket> <service> <command> [--agent-id <id>]

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

Discovery

`list`

List all services and their commands from the embedded registry

Usage:

ai-gateway list [--service <name>] [--category <name>]

Options:

--service: Filter by service name
--category: Filter by category name

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

`search`

Search across all services and commands using TF-IDF + substring matching

Usage:

ai-gateway search <query> [--limit <N>]

Options:

--limit: Maximum number of results to return

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

`help`

Show detailed help for a service or specific command

Usage:

ai-gateway help <service> [command]

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 zeroclaw --json

`capabilities`

Show effective capabilities for an AI agent identity

Usage:

ai-gateway capabilities [--agent-id <id>] [--agent-token <token>]

Options:

--agent-id: Agent profile (kodachi-claw/nullclaw/agentzero/openclaw/picoclaw/nanoclaw/claude-code/gpt/gemini/open-interpreter; aliases: zeroclaw, nanclaw, "claude code", "open interpreter")
--agent-token: Optional token for authenticated agent profiles

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

Execution

`run`

Validate and execute a binary command through the safety layer

Usage:

ai-gateway run <service> --command <cmd> [--args <args>...] [--args-json <json>] [--dry-run] [--timeout <secs>] [--agent-id <id>] [--agent-token <token>] [--approval-ticket <ticket>] OR ai-gateway run --batch-json <json> --agent-id <id> --agent-token <token>

Options:

--command: Command to execute (required)
--args: Command arguments (multiple)
--args-json: Command arguments as JSON object/array
--batch-json: Batch execution payload for trusted agents (JSON array, sequential mode only)
--dry-run: Validate without executing
--timeout: Execution timeout in seconds
--confirm: Approval token for commands requiring confirmation
--approval-ticket: Human-issued approval ticket for Active/Dangerous commands
--agent-id: Agent profile (trusted profiles require token auth)
--agent-token: Agent auth token for token-required profiles

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 '{"country":"de"}' --dry-run --json

ai-gateway run dns-leak --command test --dry-run --json-pretty

ai-gateway run kodachi-claw --command status --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --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":"kodachi-claw","command":"status"},{"service":"kodachi-claw","command":"doctor","dry_run":true}]' --json

ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json

Operational Scenarios

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

Scenario 1: Service Discovery

Discover and explore all available Kodachi services and commands

Step 1: List all services with their commands in JSON format

ai-gateway list --json

Expected Output: JSON array of all discovered services with metadata

Step 2: List commands for a specific service

ai-gateway list --service tor-switch --json

Expected Output: Commands for tor-switch with descriptions and risk tiers

Step 3: List health-control commands in text format

ai-gateway list --service health-control

Expected Output: Formatted list of health-control commands

Scenario 2: Command Search

Search across all services using TF-IDF + substring hybrid search engine

Step 1: Search for Tor exit node commands

ai-gateway search "tor exit node" --json

Expected Output: Ranked results with relevance scores

Note

Uses TF-IDF cosine similarity + substring matching

Step 2: Search with limited results

ai-gateway search "dns leak" --limit 5 --json

Expected Output: Top 5 matching commands for DNS leak operations

Step 3: Search for network check commands in text format

ai-gateway search "network check"

Expected Output: Numbered list of matching commands with scores

Step 4: Find all panic/emergency commands

ai-gateway search "panic" --json

Expected Output: Emergency commands with Dangerous risk tier

Note

Dangerous commands are blocked unless pentest mode

Scenario 3: Service Help

Get detailed help for any service or specific command

Step 1: Full specification for tor-switch service

ai-gateway help tor-switch --json

Expected Output: JSON with all commands, options, examples, features, requirements

Step 2: Help for a specific command

ai-gateway help health-control security-status --json

Expected Output: Detailed command spec with parameters and examples

Step 3: Text help for dns-switch service

ai-gateway help dns-switch

Expected Output: Formatted help output for dns-switch

Step 4: Pretty-printed JSON help for ip-fetch

ai-gateway help ip-fetch --json-pretty

Expected Output: Indented JSON with full service specification

Scenario 4: Safe Command Execution

Validate first, then execute when appropriate. No env var is needed for passive/active commands.

Step 1: Step 1 (validate): preview a passive command

ai-gateway run tor-switch --command tor-status --dry-run --json

Expected Output: Validation result without actual execution

Note

Always use --dry-run first for safety

Step 2: Step 2 (apply): execute passive command (no env needed)

ai-gateway run tor-switch --command tor-status --json

Expected Output: Live command execution result

Note

Passive commands execute without KODACHI_PENTEST_MODE

Step 3: Active command flow (no env needed): validate with explicit confirmation

ai-gateway run tor-switch --command set-exit-node --args-json '{"country":"de"}' --confirm --dry-run --json

Expected Output: Validated active operation with parsed args-json

Note

For active commands, remove --dry-run to apply changes

Step 4: Dry-run DNS leak test with custom timeout

ai-gateway run dns-leak --command test --dry-run --timeout 60 --json

Expected Output: Validation result for dns-leak test

Note

Timeout can be overridden with KODACHI_TOOL_TIMEOUT_MS env var

Step 5: Dry-run ip-fetch fetch command

ai-gateway run ip-fetch --command fetch --dry-run --json

Expected Output: Validation result for ip-fetch fetch

Note

Dry-run keeps examples deterministic in offline/auth-restricted environments

Step 6: Pass structured JSON arguments for agent-safe invocation

ai-gateway run tor-switch --command set-exit-node --args-json '{"country":"de"}' --dry-run --json

Expected Output: Dry-run validation with args expanded from JSON

Note

`--args-json` avoids brittle shell quoting in agent pipelines

Scenario 5: Safety Policy

View and understand the safety policy configuration

Step 1: Show current safety policy as JSON

ai-gateway policy show --json

Expected Output: Policy with risk tiers, allowlists, and pentest mode status

Step 2: Show safety policy in text format

ai-gateway policy show

Expected Output: Formatted policy display

Step 3: Pretty-printed policy configuration

ai-gateway policy show --json-pretty

Expected Output: Indented JSON with complete policy details

Note

Run with inline env: KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --confirm --json

Step 4: Dangerous command flow: env var required in addition to explicit confirm

KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --confirm "I understand" --dry-run --json

Expected Output: Dangerous command validated in dry-run mode with explicit confirmation token

Note

KODACHI_PENTEST_MODE is required only for dangerous commands

Scenario 6: Administration

Index management and system health checks

Step 1: Rebuild the search index

ai-gateway index rebuild --json

Expected Output: Index statistics with service and command counts

Step 2: Check health of all registered binaries

ai-gateway doctor --json

Expected Output: Health report for each binary (exists, responds, version, size)

Step 3: Health check in text format

ai-gateway doctor

Expected Output: Table showing binary health status

Scenario 7: Output Formats

All commands support multiple output formats

Step 1: Standard JSON output (compact)

ai-gateway list --json

Expected Output: Compact JSON response

Step 2: Pretty-printed JSON with indentation

ai-gateway list --json-pretty

Expected Output: Indented JSON for readability

Step 3: Enhanced human-friendly JSON (like jq)

ai-gateway list --json-human

Expected Output: Color-highlighted JSON output

Step 4: Show version information

ai-gateway --version

Expected Output: ai-gateway version 9.0.1

Step 5: Show detailed program info as JSON

ai-gateway --info --json

Expected Output: JSON with features, security, requirements

Scenario 8: AI Agent Integration

How Kodachi AI standardizes execution for agentzero/openclaw/picoclaw/kodachi-claw/nullclaw/nanoclaw/open-interpreter via one gateway contract

Step 1: AI agent finds the best matching command

ai-gateway search "check tor status" --limit 1 --json

Expected Output: Top matching command with service and invocation

Note

ai-cmd delegates execution through ai-gateway; pipe to jq externally if needed

Step 2: AI agent validates before executing

ai-gateway run tor-switch --command tor-status --dry-run --json

Expected Output: Validation passes, shows what would run

Note

Safety layer prevents dangerous commands from AI agents

Step 3: AI agent executes passive command (no env required)

ai-gateway run tor-switch --command tor-status --json

Expected Output: Live tor-status execution result

Note

Passive command execution does not require KODACHI_PENTEST_MODE

Step 4: Kodachi Claw integration path through ai-gateway

ai-gateway run kodachi-claw --command status --dry-run --json

Expected Output: Validation for kodachi-claw status command

Note

Kodachi AI gives the same JSON execution contract to all agents

Step 5: AgentZero integration template (must be in allowlist)

ai-gateway run agentzero --command status --dry-run --json

Expected Output: Policy + invocation validation for agentzero

Note

Add agentzero to the default allowlist in policy_engine.rs

Step 6: OpenClaw integration template

ai-gateway run openclaw --command status --dry-run --json

Expected Output: Policy + invocation validation for openclaw

Note

Use --dry-run first, then remove --dry-run to execute

Step 7: PicoClaw integration template

ai-gateway run picoclaw --command status --dry-run --json

Expected Output: Policy + invocation validation for picoclaw

Note

Same API shape as ai-cmd and zeroclaw integrations

Step 8: Kodachi Claw live execution path (no allow-all env required when installed/allowlisted)

ai-gateway run kodachi-claw --command status --json

Expected Output: Live kodachi-claw command output through gateway safety layer

Step 9: NullClaw integration template

ai-gateway run nullclaw --command status --dry-run --json

Expected Output: Policy + invocation validation for nullclaw

Note

Ensure nullclaw is in the policy engine allowlist

Step 10: NanoClaw integration template

ai-gateway run nanoclaw --command status --dry-run --json

Expected Output: Policy + invocation validation for nanoclaw

Note

Consistent gateway contract keeps agent integrations simple

Step 11: AI agent gets command specification

ai-gateway help tor-switch tor-status --json

Expected Output: Full command spec for AI to understand parameters

Note

Use jq in your shell after this command for field extraction

Scenario 9: Agent Security

Identity verification, capability discovery, and approval-ticket workflow

Step 1: Discover what kodachi-claw is allowed to do

ai-gateway capabilities --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --json

Expected Output: Effective services, max risk tier, and per-minute rate limit

Step 2: Discover trusted GPT agent capabilities

ai-gateway capabilities --agent-id gpt --agent-token $KODACHI_AGENT_TOKEN_GPT --json

Expected Output: Trusted profile details for gpt

Step 3: Discover trusted Claude Code agent capabilities

ai-gateway capabilities --agent-id claude-code --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json

Expected Output: Trusted profile details for claude-code

Step 4: Discover trusted Gemini agent capabilities

ai-gateway capabilities --agent-id gemini --agent-token $KODACHI_AGENT_TOKEN_GEMINI --json

Expected Output: Trusted profile details for gemini

Step 5: Discover trusted Open Interpreter agent capabilities

ai-gateway capabilities --agent-id open-interpreter --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json

Expected Output: Trusted profile details for open-interpreter

Step 6: Discover trusted OpenClaw agent capabilities

ai-gateway capabilities --agent-id openclaw --agent-token $KODACHI_AGENT_TOKEN_OPENCLAW --json

Expected Output: Trusted profile details for openclaw

Step 7: Discover trusted PicoClaw agent capabilities

ai-gateway capabilities --agent-id picoclaw --agent-token $KODACHI_AGENT_TOKEN_PICOCLAW --json

Expected Output: Trusted profile details for picoclaw

Step 8: Discover trusted NanoClaw agent capabilities

ai-gateway capabilities --agent-id nanoclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json

Expected Output: Trusted profile details for nanoclaw

Step 9: Human issues time-limited approval ticket for an active/dangerous operation

ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json

Expected Output: Signed approval ticket string

Note

Requires KODACHI_GATEWAY_APPROVAL_SECRET; extract .data.ticket with jq externally

Step 10: Agent executes command using identity + approval workflow

ai-gateway run health-control --command block-internet --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --approval-ticket "$TICKET" --json

Expected Output: Execution gated by identity policy, rate limit, and ticket verification

Note

Without valid ticket, execution returns requires_approval

Environment Variables

Variable	Description	Default	Values
`RUST_LOG`	Set logging level	info	error\|warn\|info\|debug\|trace
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

Code	Description
0	Success
2	Invalid arguments
5	File not found
1	General error
3	Permission denied
4	Network error