aegis

Aegis

   

Stop putting API keys where AI agents can read them.

Aegis is a local-first credential isolation proxy for AI agents. It sits between your agent and the APIs it calls — injecting secrets at the network boundary so the agent never sees, stores, or transmits real credentials.

<p align="center"> <img src="docs/assets/demo.gif" alt="Aegis demo" width="720" /> </p>

How It Works

<p align="center"> <img src="docs/assets/how-it-works.svg" alt="How Aegis works — agent sends request through Gate, credentials injected at the network boundary" width="900" /> </p>

Why?

AI agents (Claude, GPT, Cursor, custom bots) increasingly call real APIs — Slack, GitHub, Stripe, databases. The current pattern is dangerous:

1. Agents see raw API keys — one prompt injection exfiltrates them
2. No domain guard — a compromised agent can send your Slack token to evil.com
3. No audit trail — you can't see what an agent did with your credentials
4. No access control — every agent can use every credential

Aegis solves all four. Your agent makes HTTP calls through a local proxy. Aegis handles authentication, enforces domain restrictions, and logs everything.

Quick Start

# Install
npm install -g @getaegis/cli

# Initialize (stores master key in OS keychain by default)
aegis init

# Add a credential
aegis vault add \
  --name slack-bot \
  --service slack \
  --secret "xoxb-your-token-here" \
  --domains slack.com

# Start the proxy
aegis gate --no-agent-auth

# Test it — Aegis injects the token, forwards to Slack, logs the request
# X-Target-Host tells Gate which upstream server to forward to (optional if credential has one domain)
curl http://localhost:3100/slack/api/auth.test \
  -H "X-Target-Host: slack.com"

Production Setup (with agent auth)

# Create an agent identity
aegis agent add --name "my-agent"
# Save the printed token — it's shown once only

# Grant it access to specific credentials
aegis agent grant --agent "my-agent" --credential "slack-bot"

# Start Gate (agent auth is on by default)
aegis gate

# Agent must include its token
curl http://localhost:3100/slack/api/auth.test \
  -H "X-Target-Host: slack.com" \
  -H "X-Aegis-Agent: aegis_a1b2c3d4..."

MCP Integration

Aegis is a first-class MCP server. Any MCP-compatible AI agent can use it natively — no HTTP calls needed.

Before (plaintext key in config): ``json { "mcpServers": { "slack": { "command": "node", "args": ["slack-mcp-server"], "env": { "SLACK_TOKEN": "xoxb-1234-real-token-here" } } } } ``

After (Aegis — no key visible): ``json { "mcpServers": { "aegis": { "command": "npx", "args": ["-y", "@getaegis/cli", "mcp", "serve"] } } } ``

Generate the config for your AI host:

aegis mcp config claude   # Claude Desktop
aegis mcp config cursor   # Cursor
aegis mcp config vscode   # VS Code
aegis mcp config cline    # Cline
aegis mcp config windsurf # Windsurf

The MCP server exposes three tools:

| Tool | Description | |------|-------------| | aegis_proxy_request | Make an authenticated API call (provide service + path, Aegis injects credentials) | | aegis_list_services | List available services (names only, never secrets) | | aegis_health | Check Aegis status |

The MCP server replicates the full Gate security pipeline: domain guard, agent auth, body inspection, rate limiting, audit logging.

Setup Guides

• Claude Desktop
• Cursor
• VS Code
• Windsurf
• Cline
• OpenClaw — personal AI assistant (HTTP proxy + skill)

Features

| Feature | Description | |---------|-------------| | Encrypted Vault | AES-256-GCM encrypted credential storage with PBKDF2 key derivation | | HTTP Proxy (Gate) | Transparent credential injection — agent hits localhost:3100/{service}/path | | Domain Guard | Every outbound request checked against credential allowlists. No bypass | | Audit Ledger | Every request (allowed and blocked) logged with full context | | Agent Identity | Per-agent tokens, credential scoping, and rate limits | | Policy Engine | Declarative YAML policies — method, path, rate-limit, time-of-day restrictions | | Body Inspector | Outbound request bodies scanned for credential-like patterns | | MCP Server | Native Model Context Protocol for Claude, Cursor, VS Code, Windsurf, Cline | | Web Dashboard | Real-time monitoring UI with WebSocket live feed | | Prometheus Metrics | /_aegis/metrics endpoint for Grafana dashboards | | Webhook Alerts | HMAC-signed notifications for blocked requests, expiring credentials | | RBAC | Admin, operator, viewer roles with 16 granular permissions | | Multi-Vault | Separate vaults for dev/staging/prod with isolated encryption keys | | Shamir's Secret Sharing | M-of-N key splitting for team master key management | | Cross-Platform Key Storage | OS keychain by default (macOS, Windows, Linux) with file fallback | | TLS Support | Optional HTTPS on Gate with cert/key configuration | | Configuration File | aegis.config.yaml with env var overrides and CLI flag overrides |

Example Integrations

Step-by-step guides with config files and policies included:

• Slack Bot — Protect your Slack bot token with domain-restricted proxy access
• GitHub Integration — Secure GitHub PAT with per-agent grants and read-only policies
• Stripe Backend — Isolate Stripe API keys with body inspection and rate limiting
• OpenClaw Skill — Aegis skill for OpenClaw personal AI assistant

Security

• Published STRIDE threat model — 28 threats analysed, 0 critical/high unmitigated findings
• Full security architecture documentation (trust boundaries, crypto pipeline, data flow)
• AES-256-GCM + ChaCha20-Poly1305 encryption at rest
• Domain guard enforced on every request — no bypass
• Agent tokens stored as SHA-256 hashes — cannot be recovered, only regenerated
• Request body inspection for credential pattern detection
• Open source (Apache 2.0) — read the code

How Aegis Compares

| | .env files | Vault/Doppler | Infisical | Aegis | |---|---|---|---|---| | Agent sees raw key | Yes | Yes (after fetch) | Yes (after fetch) | No — never | | Domain restrictions | No | No | No | Yes | | MCP-native | No | No | Adding | Yes | | Local-first | Yes | No | No | Yes | | Setup | 10 sec | 30+ min | 15+ min | ~2 min |

See full comparison for detailed breakdowns against each approach.

Documentation

| Document | Description | |----------|-------------| | Usage Guide | Full reference: CLI commands, configuration, RBAC, policies, webhooks, troubleshooting | | Security Architecture | Trust boundaries, crypto pipeline, data flow diagrams | | Threat Model | STRIDE analysis — 28 threats, mitigations, residual risks | | Comparison | Detailed comparison with .env, Vault, Doppler, Infisical | | FAQ | Common questions and objections | | Roadmap | Feature roadmap | | Contributing | Code style, PR process, architecture overview |

Install

# npm
npm install -g @getaegis/cli

# Homebrew
brew tap getaegis/aegis && brew install aegis

# Docker
docker run ghcr.io/getaegis/aegis --help

Requires Node.js ≥ 20 — check with node -v

Development

git clone https://github.com/getaegis/aegis.git
cd aegis
yarn install
yarn build
yarn test

See CONTRIBUTING.md for code style, PR process, and architecture overview.

License

Apache 2.0