AIMux Documentation

AIMux is a security-focused service mesh for AI agent networks. It provides centralized governance over agent-to-agent communication through identity-based access control, semantic routing, and audit logging.

What's New in v0.3.1

  • Zero-Trust Identity Modes — Legacy, zero-trust, and hybrid runtime modes with HMAC-SHA256 and mTLS verification
  • Sidecar Proxy — Drop-in sidecar that intercepts, signs, and enforces policy at the pod level
  • Circuit Breaker — Per-upstream and per-agent circuit breakers with automatic recovery
  • Reputation Engine — Track agent error rates and automatically isolate misbehaving agents
  • APT Package — Native Debian/Ubuntu installation via APT repository

Core Problem & Solution

The Challenge: How do you monitor and control what AI agents can access? Traditional API gateways lack agent intent understanding.

The Solution: AIMux enforces policy at the infrastructure level rather than relying on agents for self-governance.

Quick Start

Get AIMux running in under 2 minutes:

bash
git clone https://github.com/techspeque/aimux.git
cd aimux
make run

Test it out:

bash
# Basic query
curl "http://localhost:8080?q=what+is+50+times+3"

# View dashboard
curl "http://localhost:8080/dashboard/"

Demo Mode

Run a full Agent Service Mesh simulation demonstrating semantic routing, ACL enforcement, and authentication:

bash
make demo

Installation

📦 Homebrew

bash
brew install techspeque/aimux/aimux

🐳 Docker

bash
docker run -p 8080:8080 ghcr.io/techspeque/aimux:latest

📥 Binary Release

Pre-built binaries for Linux and macOS:

bash
curl -LO https://github.com/techspeque/aimux/releases/latest/download/aimux-linux-amd64.tar.gz tar -xzf aimux-linux-amd64.tar.gz ./aimux -config aimux.yaml

🔨 Build from Source

Requires Go 1.22+:

bash
git clone https://github.com/techspeque/aimux.git
cd aimux
make build

🐧 Debian/Ubuntu

Download the .deb package from the latest release:

bash
curl -LO https://github.com/techspeque/aimux/releases/download/v0.3.1/aimux_0.3.1_amd64.deb
sudo dpkg -i aimux_*.deb
sudo systemctl start aimux

Or add the APT repository for automatic updates:

bash
curl -fsSL https://techspeque.github.io/aimux/public.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/aimux-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/aimux-archive-keyring.gpg] https://techspeque.github.io/aimux stable main" \
  | sudo tee /etc/apt/sources.list.d/aimux.list
sudo apt update && sudo apt install aimux

Configuration

AIMux uses a YAML configuration file to define server settings, semantic engine parameters, agents, and routes.

yaml
server:
  port: 8080

runtime:
  mode: "zero-trust"              # legacy | zero-trust | hybrid
  principal_header: "X-AIMux-Principal"
  principal_signature_header: "X-AIMux-Principal-Signature"
  principal_signature_secret: "change-me"  # HMAC-SHA256 secret

reputation:
  error_threshold: 5              # Errors before circuit opens
  circuit_reset_timeout: "1m"     # Time before half-open retry

logging:
  level: info
  timestamp: true

semantic_engine:
  model_path: "./models/all-MiniLM-L6-v2.onnx"
  min_score: 0.40
  ambiguity_threshold: 0.05

agents:
  - finance-bot
  - admin-bot
  - data-processor

routes:
  - name: "finance"
    upstream: "http://finance:8001"
    intents:
      - "analyze budget"
      - "forecast revenue"
    allowed:
      - finance-bot
      - admin-bot

  - name: "legal"
    upstream: "http://legal:8002"
    require_verification: true      # Require upstream ZKP/TEE attestation
    intents:
      - "review nda"
      - "check compliance"
    allowed:
      - legal-bot
      - admin-bot

fallback:
  upstream: "http://ollama:11434"

Configuration Fields

  • server.port - HTTP server port (default: 8080)
  • runtime.mode - Identity mode: legacy, zero-trust, or hybrid
  • runtime.principal_header - Signed principal header name (default: X-AIMux-Principal)
  • runtime.principal_signature_header - Signature header name (default: X-AIMux-Principal-Signature)
  • runtime.principal_signature_secret - HMAC secret for signed principal verification
  • reputation.error_threshold - Number of errors before the circuit breaker opens
  • reputation.circuit_reset_timeout - Duration before attempting half-open recovery
  • logging.level - Log level: debug, info, warn, error
  • semantic_engine.min_score - Minimum similarity threshold (0-1)
  • semantic_engine.ambiguity_threshold - Max score difference for ambiguity detection
  • agents - List of registered agent identities
  • routes[].require_verification - Require upstream X-AIMux-ZKP-Attestation or X-AIMux-TEE-Quote header
  • routes - Semantic routes with intents and ACLs
  • fallback.upstream - Default route when no semantic match found

Agent Service Mesh

Identity Extraction

Identity extraction depends on the runtime mode:

Legacy Mode

  1. URL query parameters: client_id, agent, source
  2. HTTP headers: X-Source-Agent, X-Client-ID
  3. JSON body: agent field

Zero-Trust Mode

  1. mTLS client certificate (SPIFFE ID or CN)
  2. Signed principal: X-AIMux-Principal + X-AIMux-Principal-Signature (HMAC-SHA256)

Hybrid Mode

Tries zero-trust extraction first, falls back to legacy if no cryptographic identity is present.

Example:

bash
# Legacy mode — via header
curl -H "X-Source-Agent: finance-bot" \
  -d '{"query": "analyze revenue"}' \
  http://localhost:8080

# Zero-trust mode — signed principal
PRINCIPAL="finance-bot"
SIG=$(printf "%s" "$PRINCIPAL" | openssl dgst -sha256 -hmac "change-me" -binary | xxd -p -c 256)
curl -H "X-AIMux-Principal: $PRINCIPAL" \
  -H "X-AIMux-Principal-Signature: $SIG" \
  -H "X-AIMux-Query-Hint: analyze revenue" \
  http://localhost:8080

Access Control Levels

🔒 Restricted Routes

Specific agents only via allowed field:

yaml
routes:
  - name: "admin"
    upstream: "http://admin:8004"
    allowed:
      - admin-bot  # Only admin-bot can access

🌐 Public Routes

All registered agents using wildcard:

yaml
routes:
  - name: "public-api"
    upstream: "http://api:8000"
    allowed:
      - "*"  # Any registered agent

🔓 Open Routes

No ACL field means all access including anonymous:

yaml
routes:
  - name: "health"
    upstream: "http://health:8080"
    # No 'allowed' field = completely open

Agent Naming Convention

Agent names must use snake_case or kebab-case:

✓ Valid

  • finance-bot
  • data_processor
  • admin-agent-v2

✗ Invalid

  • FinanceBot
  • finance.bot
  • finance bot

Error Responses

  • 401 Unauthorized - Unregistered client identity
  • 403 Forbidden - Client not permitted for route, anonymous access to restricted route, or circuit breaker open
  • 502 Bad Gateway - Upstream failed to provide required cryptographic verification (ZKP/TEE)

Identity Modes

AIMux v0.3.1 introduces three runtime identity modes. Choose the level of trust verification that matches your deployment.

Legacy

Header-based identity. Trusts the agent name in headers/query params without cryptographic verification.

yaml
runtime:
  mode: "legacy"

Best for: development, internal networks

Zero-Trust

Every request must be cryptographically verified via HMAC-SHA256 or mTLS. No implicit trust.

yaml
runtime:
  mode: "zero-trust"
  principal_signature_secret: "secret"

Best for: production, multi-tenant

Hybrid

Zero-trust when credentials are present, legacy fallback otherwise. Enables gradual migration.

yaml
runtime:
  mode: "hybrid"
  principal_signature_secret: "secret"

Best for: migration, mixed fleets

HMAC-SHA256 Verification

In zero-trust mode, agents sign their principal name with a shared secret. AIMux recomputes the HMAC and rejects mismatches. The sidecar handles this automatically.

bash
# Sign the principal and send a request
PRINCIPAL="finance-bot"
SIG=$(printf "%s" "$PRINCIPAL" | openssl dgst -sha256 -hmac "change-me" -binary | xxd -p -c 256)

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -H "X-AIMux-Principal: $PRINCIPAL" \
  -H "X-AIMux-Principal-Signature: $SIG" \
  -H "X-AIMux-Query-Hint: analyze revenue" \
  -d '{"messages":[{"role":"user","content":"analyze revenue"}]}'

mTLS & SPIFFE Support

When mTLS is enabled, AIMux extracts the agent identity from the client certificate's Common Name (CN) or SPIFFE ID (SAN URI). This provides the strongest identity guarantee — no shared secrets required.

bash
# Agent connects with client cert
curl --cert agent.crt --key agent.key \
  --cacert ca.crt \
  -d '{"query": "analyze revenue"}' \
  https://aimux.internal:8443

Verification Middleware

Use require_verification: true on strict routes to require the upstream to provide a cryptographic attestation header (X-AIMux-ZKP-Attestation or X-AIMux-TEE-Quote). Returns 502 if the upstream fails to provide it.

yaml
routes:
  - name: "legal"
    upstream: "http://legal:8002"
    require_verification: true  # Require upstream ZKP or TEE attestation
    allowed:
      - legal-bot
      - admin-bot

Sidecar Proxy

For zero-trust deployments, run aimux-sidecar next to each agent. The sidecar forwards traffic to AIMux while injecting signed identity headers.

How It Works

  1. Agent sends request to localhost:8081 (sidecar listen port)
  2. Sidecar injects X-AIMux-Principal header with the agent identity
  3. Sidecar signs the principal with HMAC-SHA256 into X-AIMux-Principal-Signature
  4. Sidecar sniffs the payload and adds X-AIMux-Query-Hint when possible
  5. Gateway verifies the signature and routes to the correct upstream

Sidecar Configuration

yaml
# sidecar.yaml
listen_port: 8081
gateway_url: http://127.0.0.1:8080
agent_id: finance-bot
signature_secret: change-me

# Optional mTLS client certificate for sidecar->gateway transport
# cert_file: /etc/aimux/certs/agent.crt
# key_file: /etc/aimux/certs/agent.key

Running the Sidecar

bash
# Build the sidecar binary
go build -o bin/aimux-sidecar ./cmd/sidecar

# Run alongside your agent
./bin/aimux-sidecar -config sidecar.yaml

# Then point your agent to localhost:8081 instead of the gateway

Injected Headers

  • X-AIMux-Principal - Agent identity from agent_id config
  • X-AIMux-Principal-Signature - HMAC-SHA256 of the principal name
  • X-AIMux-Query-Hint - Intent sniffed from the request payload (when available)
  • cert_file / key_file - Optional mTLS client certificate for gateway transport

Circuit Breaker

AIMux tracks error rates per-upstream and per-agent, automatically opening circuit breakers to prevent cascading failures.

Configuration

yaml
reputation:
  error_threshold: 5           # Consecutive failures before circuit opens
  circuit_reset_timeout: "1m"  # Time before half-open retry

Circuit States

Closed

Normal operation. Requests flow through. Errors are counted.

Open

Error threshold exceeded. All requests are immediately rejected with 403 (circuit breaker open).

Half-Open

After circuit_reset_timeout, one probe request is allowed. Success closes the circuit; failure re-opens it.

Behavior Details

  • Per-upstream tracking: Each upstream has its own circuit breaker. If finance:8001 is down, requests to admin:8004 are unaffected.
  • Per-agent tracking: A misbehaving agent's errors are attributed to that agent. Other agents hitting the same upstream are not penalized.
  • Reset on success: A successful request in half-open state resets the error counter and closes the circuit.
  • Prometheus visibility: Circuit state changes emit aimux_circuit_breaker_state metrics for alerting and dashboards.

API Reference

AIMux exposes several management and observability endpoints:

GET/healthz

Health check endpoint

GET/metrics

Prometheus metrics endpoint

GET/routes

List all configured routes

GET/agents

List all registered agents

GET/config

View current configuration

GET/dashboard/

Built-in web UI for monitoring

OpenAI Compatible

AIMux accepts standard OpenAI chat completion format:

bash
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Source-Agent: finance-bot" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "analyze Q3 revenue"}
    ]
  }'

Development

Build

bash
make build

Run Tests

bash
make test

Debug Logging

Enable detailed logging in your config:

yaml
logging:
  level: debug
  timestamp: true

License

AIMux is released under the MIT License. Free for personal and commercial use.

Additional Resources

→ GitHub Repository→ Report Issues→ View Releases