getaegis/aegis

CI npm version Docker License

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.

How It Works

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):

{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["slack-mcp-server"],
      "env": { "SLACK_TOKEN": "xoxb-1234-real-token-here" }
    }
  }
}

After (Aegis — no key visible):

{
  "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