{
"markdown": "# Aegis\n\n[](https://github.com/getaegis/aegis/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/@getaegis/cli)\n[](https://ghcr.io/getaegis/aegis)\n[](LICENSE)\n\n**Stop putting API keys where AI agents can read them.**\n\nAegis 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.\n\n
\n \n
\n\n## How It Works\n\n
\n \n
\n\n## Why?\n\nAI agents (Claude, GPT, Cursor, custom bots) increasingly call real APIs — Slack, GitHub, Stripe, databases. The current pattern is dangerous:\n\n1. **Agents see raw API keys** — one prompt injection exfiltrates them\n2. **No domain guard** — a compromised agent can send your Slack token to `evil.com`\n3. **No audit trail** — you can't see what an agent did with your credentials\n4. **No access control** — every agent can use every credential\n\nAegis solves all four. Your agent makes HTTP calls through a local proxy. Aegis handles authentication, enforces domain restrictions, and logs everything.\n\n## Quick Start\n\n```bash\n# Install\nnpm install -g @getaegis/cli\n\n# Initialize (stores master key in OS keychain by default)\naegis init\n\n# Add a credential\naegis vault add \\\n --name slack-bot \\\n --service slack \\\n --secret \"xoxb-your-token-here\" \\\n --domains slack.com\n\n# Start the proxy\naegis gate --no-agent-auth\n\n# Test it — Aegis injects the token, forwards to Slack, logs the request\n# X-Target-Host tells Gate which upstream server to forward to (optional if credential has one domain)\ncurl http://localhost:3100/slack/api/auth.test \\\n -H \"X-Target-Host: slack.com\"\n```\n\n### Production Setup (with agent auth)\n\n```bash\n# Create an agent identity\naegis agent add --name \"my-agent\"\n# Save the printed token — it's shown once only\n\n# Grant it access to specific credentials\naegis agent grant --agent \"my-agent\" --credential \"slack-bot\"\n\n# Start Gate (agent auth is on by default)\naegis gate\n\n# Agent must include its token\ncurl http://localhost:3100/slack/api/auth.test \\\n -H \"X-Target-Host: slack.com\" \\\n -H \"X-Aegis-Agent: aegis_a1b2c3d4...\"\n```\n\n## MCP Integration\n\nAegis is a first-class [MCP](https://modelcontextprotocol.io) server. Any MCP-compatible AI agent can use it natively — no HTTP calls needed.\n\n**Before (plaintext key in config):**\n```json\n{\n \"mcpServers\": {\n \"slack\": {\n \"command\": \"node\",\n \"args\": [\"slack-mcp-server\"],\n \"env\": { \"SLACK_TOKEN\": \"xoxb-1234-real-token-here\" }\n }\n }\n}\n```\n\n**After (Aegis — no key visible):**\n```json\n{\n \"mcpServers\": {\n \"aegis\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@getaegis/cli\", \"mcp\", \"serve\"]\n }\n }\n}\n```\n\nGenerate the config for your AI host:\n\n```bash\naegis mcp config claude # Claude Desktop\naegis mcp config cursor # Cursor\naegis mcp config vscode # VS Code\naegis mcp config cline # Cline\naegis mcp config windsurf # Windsurf\n```\n\nThe MCP server exposes three tools:\n\n| Tool | Description |\n|------|-------------|\n| `aegis_proxy_request` | Make an authenticated API call (provide service + path, Aegis injects credentials) |\n| `aegis_list_services` | List available services (names only, never secrets) |\n| `aegis_health` | Check Aegis status |\n\nThe MCP server replicates the full Gate security pipeline: domain guard, agent auth, body inspection, rate limiting, audit logging.\n\n### Setup Guides\n\n- [Claude Desktop](docs/guides/claude-desktop.md)\n- [Cursor](docs/guides/cursor.md)\n- [VS Code](docs/guides/vscode.md)\n- [Windsurf](docs/guides/windsurf.md)\n- [Cline](docs/guides/cline.md)\n- [OpenClaw](docs/guides/openclaw.md) — personal AI assistant (HTTP proxy + skill)\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Encrypted Vault** | AES-256-GCM encrypted credential storage with PBKDF2 key derivation |\n| **HTTP Proxy (Gate)** | Transparent credential injection — agent hits `localhost:3100/{service}/path` |\n| **Domain Guard** | Every outbound request checked against credential allowlists. No bypass |\n| **Audit Ledger** | Every request (allowed and blocked) logged with full context |\n| **Agent Identity** | Per-agent tokens, credential scoping, and rate limits |\n| **Policy Engine** | Declarative YAML policies — method, path, rate-limit, time-of-day restrictions |\n| **Body Inspector** | Outbound request bodies scanned for credential-like patterns |\n| **MCP Server** | Native Model Context Protocol for Claude, Cursor, VS Code, Windsurf, Cline |\n| **Web Dashboard** | Real-time monitoring UI with WebSocket live feed |\n| **Prometheus Metrics** | `/_aegis/metrics` endpoint for Grafana dashboards |\n| **Webhook Alerts** | HMAC-signed notifications for blocked requests, expiring credentials |\n| **RBAC** | Admin, operator, viewer roles with 16 granular permissions |\n| **Multi-Vault** | Separate vaults for dev/staging/prod with isolated encryption keys |\n| **Shamir's Secret Sharing** | M-of-N key splitting for team master key management |\n| **Cross-Platform Key Storage** | OS keychain by default (macOS, Windows, Linux) with file fallback |\n| **TLS Support** | Optional HTTPS on Gate with cert/key configuration |\n| **Configuration File** | `aegis.config.yaml` with env var overrides and CLI flag overrides |\n\n## Example Integrations\n\nStep-by-step guides with config files and policies included:\n\n- [**Slack Bot**](examples/slack-bot/) — Protect your Slack bot token with domain-restricted proxy access\n- [**GitHub Integration**](examples/github-integration/) — Secure GitHub PAT with per-agent grants and read-only policies\n- [**Stripe Backend**](examples/stripe-backend/) — Isolate Stripe API keys with body inspection and rate limiting\n- [**OpenClaw Skill**](examples/openclaw-skill/) — Aegis skill for OpenClaw personal AI assistant\n\n## Security\n\n- Published [STRIDE threat model](docs/THREAT_MODEL.md) — 28 threats analysed, 0 critical/high unmitigated findings\n- Full [security architecture](docs/SECURITY_ARCHITECTURE.md) documentation (trust boundaries, crypto pipeline, data flow)\n- AES-256-GCM + ChaCha20-Poly1305 encryption at rest\n- Domain guard enforced on every request — no bypass\n- Agent tokens stored as SHA-256 hashes — cannot be recovered, only regenerated\n- Request body inspection for credential pattern detection\n- Open source (Apache 2.0) — read the code\n\n## How Aegis Compares\n\n| | `.env` files | Vault/Doppler | Infisical | **Aegis** |\n|---|---|---|---|---|\n| Agent sees raw key | Yes | Yes (after fetch) | Yes (after fetch) | **No — never** |\n| Domain restrictions | No | No | No | **Yes** |\n| MCP-native | No | No | Adding | **Yes** |\n| Local-first | Yes | No | No | **Yes** |\n| Setup | 10 sec | 30+ min | 15+ min | **~2 min** |\n\nSee [full comparison](docs/COMPARISON.md) for detailed breakdowns against each approach.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Usage Guide](docs/USAGE.md) | Full reference: CLI commands, configuration, RBAC, policies, webhooks, troubleshooting |\n| [Security Architecture](docs/SECURITY_ARCHITECTURE.md) | Trust boundaries, crypto pipeline, data flow diagrams |\n| [Threat Model](docs/THREAT_MODEL.md) | STRIDE analysis — 28 threats, mitigations, residual risks |\n| [Comparison](docs/COMPARISON.md) | Detailed comparison with .env, Vault, Doppler, Infisical |\n| [FAQ](docs/FAQ.md) | Common questions and objections |\n| [Roadmap](docs/ROADMAP.md) | Feature roadmap |\n| [Contributing](CONTRIBUTING.md) | Code style, PR process, architecture overview |\n\n## Install\n\n```bash\n# npm\nnpm install -g @getaegis/cli\n\n# Homebrew\nbrew tap getaegis/aegis && brew install aegis\n\n# Docker\ndocker run ghcr.io/getaegis/aegis --help\n```\n\n**Requires Node.js ≥ 20** — check with `node -v`\n\n## Development\n\n```bash\ngit clone https://github.com/getaegis/aegis.git\ncd aegis\nyarn install\nyarn build\nyarn test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for code style, PR process, and architecture overview.\n\n## License\n\n[Apache 2.0](LICENSE)\n",
"bytes": 8494,
"sha": "1a3b967987640773b231cdb41315f36e4dfa746a927f39d92e5b788231daf518",
"repo_slug": "getaegis/aegis",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_getaegis_aegis_771285c9/readme"
}
![\"Aegis](\"docs/assets/demo.gif\")
\n![\"How](\"docs/assets/how-it-works.svg\")
\n