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.

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

Configuration

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

yaml

server:
  port: 8080

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"
      - "quarterly earnings"
    allowed:
      - finance-bot
      - admin-bot

  - name: "admin"
    upstream: "http://admin:8004"
    intents:
      - "delete users"
      - "reset database"
    allowed:
      - admin-bot

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

Configuration Fields

server.port - HTTP server port (default: 8080)
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 - Semantic routes with intents and ACLs
fallback.upstream - Default route when no semantic match found

Agent Service Mesh

Identity Extraction

AIMux extracts agent identity in priority order:

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

Example:

bash

# Via query param
curl "http://localhost:8080?client_id=finance-bot&q=analyze+revenue"

# Via header
curl -H "X-Source-Agent: finance-bot" \
  -d '{"query": "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 or anonymous access to restricted route
409 Conflict - Ambiguous route matching (multiple routes with similar scores)

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