Skip to content

ai-gateway

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

Version: 9.0.1 | Size: 4.3MB | Author: Warith Al Maawali

License: Proprietary | Website: https://www.digi77.com

File Information

Property Value
Binary Name ai-gateway
Version 9.0.1
Build Date 2026-02-21T23:53:58.626096361Z
Rust Version 1.82.0
File Size 4.3MB
JSON Data View Raw JSON

SHA256 Checksum

f096ade7410fe48c07a942d1674f9490df2dd5adddfa83fbaa8b40f0e7c2077d

Features

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

Security Features

Feature Description
Inputvalidation All inputs are validated and sanitized
Ratelimiting Built-in rate limiting for network operations
Authentication Secure authentication with certificate pinning
Encryption TLS 1.3 for all network communications

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
--json-pretty Pretty-print JSON output with indentation
--json-human Enhanced JSON output with improved formatting (like jq)
--verbose Enable verbose output
--quiet Suppress non-essential output
--no-color Disable colored output
--config <FILE> Use custom configuration file
--timeout <SECS> Set timeout (default: 30)
--retry <COUNT> Retry attempts (default: 3)

Commands

Administration

index

Rebuild the search index from the embedded registry

Usage: 

ai-gateway 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 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 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 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 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 across all services and commands using TF-IDF + substring matching

Usage: 

ai-gateway 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 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 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 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

Examples

Service Discovery

Discover and explore all available Kodachi services and commands

List all services with their commands in JSON format 

ai-gateway list --json
Expected Output: JSON array of all discovered services with metadata

List commands for a specific service 

ai-gateway list --service tor-switch --json
Expected Output: Commands for tor-switch with descriptions and risk tiers

List health-control commands in text format 

ai-gateway list --service health-control
Expected Output: Formatted list of health-control commands

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

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

Search with limited results 

ai-gateway search "dns leak" --limit 5 --json
Expected Output: Top 5 matching commands for DNS leak operations

Search for network check commands in text format 

ai-gateway search "network check"
Expected Output: Numbered list of matching commands with scores

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

Service Help

Get detailed help for any service or specific command

Full specification for tor-switch service 

ai-gateway help tor-switch --json
Expected Output: JSON with all commands, options, examples, features, requirements

Help for a specific command 

ai-gateway help health-control security-status --json
Expected Output: Detailed command spec with parameters and examples

Text help for dns-switch service 

ai-gateway help dns-switch
Expected Output: Formatted help output for dns-switch

Pretty-printed JSON help for ip-fetch 

ai-gateway help ip-fetch --json-pretty
Expected Output: Indented JSON with full service specification

Safe Command Execution

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

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 (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

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

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

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

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

Safety Policy

View and understand the safety policy configuration

Show current safety policy as JSON 

ai-gateway policy show --json
Expected Output: Policy with risk tiers, allowlists, and pentest mode status

Show safety policy in text format 

ai-gateway policy show
Expected Output: Formatted policy display

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

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

Administration

Index management and system health checks

Rebuild the search index 

ai-gateway index rebuild --json
Expected Output: Index statistics with service and command counts

Check health of all registered binaries 

ai-gateway doctor --json
Expected Output: Health report for each binary (exists, responds, version, size)

Health check in text format 

ai-gateway doctor
Expected Output: Table showing binary health status

Output Formats

All commands support multiple output formats

Standard JSON output (compact) 

ai-gateway list --json
Expected Output: Compact JSON response

Pretty-printed JSON with indentation 

ai-gateway list --json-pretty
Expected Output: Indented JSON for readability

Enhanced human-friendly JSON (like jq) 

ai-gateway list --json-human
Expected Output: Color-highlighted JSON output

Show version information 

ai-gateway --version
Expected Output: ai-gateway version 9.0.1

Show detailed program info as JSON 

ai-gateway --info --json
Expected Output: JSON with features, security, requirements

AI Agent Integration

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

AI agent finds the best matching command 

ai-gateway search "check tor status" --limit 1 --json | jq '.data.results[0]'
Expected Output: Top matching command with service and invocation

Note

ai-cmd delegates execution through ai-gateway

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

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

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

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

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

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

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

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

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

AI agent gets command specification 

ai-gateway help tor-switch tor-status --json | jq '.data'
Expected Output: Full command spec for AI to understand parameters

Agent Security

Identity verification, capability discovery, and approval-ticket workflow

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

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

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

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

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

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

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

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

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 | jq -r '.data.ticket'
Expected Output: Signed approval ticket string

Note

Requires KODACHI_GATEWAY_APPROVAL_SECRET for stable verification across sessions

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
NO_COLOR Disable all colored output when set unset 1

Exit Codes

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