# Aegis

> Credential proxy for AI agents

- **Type:** MCP server
- **Install:** `agentstack add mcp-yagna-1-aegis`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yagna-1](https://agentstack.voostack.com/s/yagna-1)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [yagna-1](https://github.com/yagna-1)
- **Source:** https://github.com/yagna-1/aegis

## Install

```sh
agentstack add mcp-yagna-1-aegis
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Aegis

Secure credential proxy for AI agents

  
  
  
  
  
  
  
  
  

  Quickstart
  ·
  MCP Integration
  ·
  Security Model

A lightweight credential proxy for AI agent workflows. Sits between your agent and any API — injecting real secrets at the network boundary. The agent **never sees credentials**.

Single-binary Go runtime with a compact footprint: **~17 MB executable**, **~660 KB repo size**, and **~76 KB internal source**.

Works natively as an MCP server with **Cursor**, **Claude Desktop**, **VS Code / Cline**, and **Windsurf**.

---

## Project

- Version: `2.0.0`
- License: [Apache 2.0](https://github.com/yagna-1/aegis/blob/main/LICENSE)
- Code of Conduct: [Contributor Covenant](https://github.com/yagna-1/aegis/blob/main/CODE_OF_CONDUCT.md)
- Releases: [No releases published](https://github.com/yagna-1/aegis/releases)
- Packages: [No packages published](https://github.com/yagna-1/aegis/packages)
- Tags: [View tags](https://github.com/yagna-1/aegis/tags)

---

## The problem

```
Agent context / system prompt:
  GITHUB_TOKEN=ghp_abc123   ← agent can read this
  STRIPE_SECRET_KEY=sk_...  ← one prompt injection and it's gone
```

## The fix

```
Agent  ──►  http://localhost:8080  ──►  Aegis  ──►  api.github.com
              (no key visible)              │
                                           └── pulls GITHUB_TOKEN from Infisical
                                               at request time, never stored locally
```

---

## Quickstart (5 minutes)

### 1. Install Aegis
```bash
go install github.com/yagna-1/aegis/cmd/aegis@latest
```

Or install a prebuilt binary from the `v2.0.0` release:

```bash
# macOS (Apple Silicon)
curl -L https://github.com/yagna-1/aegis/releases/download/v2.0.0/aegis-darwin-arm64 -o aegis
chmod +x aegis && sudo mv aegis /usr/local/bin/aegis

# macOS (Intel)
curl -L https://github.com/yagna-1/aegis/releases/download/v2.0.0/aegis-darwin-amd64 -o aegis
chmod +x aegis && sudo mv aegis /usr/local/bin/aegis

# Linux (amd64)
curl -L https://github.com/yagna-1/aegis/releases/download/v2.0.0/aegis-linux-amd64 -o aegis
chmod +x aegis && sudo mv aegis /usr/local/bin/aegis
```

```powershell
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/yagna-1/aegis/releases/download/v2.0.0/aegis-windows-amd64.exe" -OutFile "aegis.exe"
```

```bash
# Optional: verify checksums
curl -L https://github.com/yagna-1/aegis/releases/download/v2.0.0/checksums.txt -o checksums.txt
shasum -a 256 aegis
```

### 2. Scaffold your project
```bash
cd ~/projects/my-agent
aegis init -services github,slack,stripe
```

### 3. Connect to Infisical (free, open source)
```bash
# Sign up free at https://app.infisical.com
# Create a Machine Identity with Universal Auth
# (Guide: https://infisical.com/docs/documentation/platform/identities/universal-auth)

aegis infisical setup
# → stores Client ID + Secret in your OS keychain
# → your actual API secrets stay in Infisical, never on disk
```

### 4. Add the Infisical block to aegis.yaml
```yaml
infisical:
  project_id: your-project-id
  environment: dev
```

### 5. Add your real secrets to Infisical
In the Infisical dashboard, add `GITHUB_TOKEN`, `STRIPE_SECRET_KEY`, etc.

### 6. Start and verify
```bash
aegis status   # checks connection + shows which secrets are found
aegis          # start proxy on :8080
```

---

## How secrets flow

```
Infisical dashboard
  → stores GITHUB_TOKEN, STRIPE_SECRET_KEY, etc.
  → your actual secrets never touch your machine's filesystem

aegis infisical setup
  → stores only the Machine Identity credentials in OS keychain
  → two values: Client ID (not secret) + Client Secret

aegis starts
  → authenticates with Infisical API using Machine Identity
  → fetches all secrets into process memory
  → auto-refreshes every 5 minutes (rotated secrets propagate automatically)

Agent calls http://localhost:8080
  → Aegis injects the real credential header
  → forwards to allowlisted domain
  → agent sees the API response, never the key
```

---

## Per-project isolation

Aegis auto-discovers `aegis.yaml` by walking up from the working directory — like `.git`:

```
~/projects/
  stripe-app/
    aegis.yaml   ← infisical.environment: prod, allowlist: api.stripe.com only
  github-bot/
    aegis.yaml   ← infisical.environment: dev, allowlist: api.github.com only
```

MCP mode inherits the IDE's working directory. Open a different project → different Infisical environment → different secrets. **No flags needed.**

---

## Secret source behavior

| Source | How | Behavior |
|---|---|---|
| **Infisical** | `infisical:` block in aegis.yaml | Strict mode: required if configured; startup fails if Infisical cannot load |
| **OS Keychain** | `${keychain:name}` in templates | Supported for template expansion at request time |
| **.env file** | Auto-discovered in project root | Used only when `infisical:` is not configured |

For agent-safe setups, use Infisical + keychain and avoid storing API keys in local `.env` files.

---

## IDE integration (MCP mode)

One config, works for all projects (auto-discovers per-project aegis.yaml).

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "aegis": { "command": "aegis", "args": ["-mode", "mcp"] }
  }
}
```

**Cursor** — `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "aegis": { "command": "aegis", "args": ["-mode", "mcp"] }
  }
}
```

**VS Code / Cline / Windsurf** — same pattern, check your tool's MCP config path.

The IDE spawns `aegis -mode mcp` as a child process automatically. The agent calls the `http_request` tool — no auth headers, no secrets in context.

---

## Proxy mode — any language

```bash
# .env or system prompt instruction for the agent:
# "Call http://localhost:8080 with header X-Aegis-Target set to the full URL"

curl http://localhost:8080 \
  -H "X-Aegis-Target: https://api.github.com/user/repos"
```

Works with Python, TypeScript, Go, Ruby — any HTTP client.

---

## `aegis status`

```
Config:  /projects/my-agent/aegis.yaml
Port:    8080

Secrets: Infisical
  Site:    https://app.infisical.com
  Project: abc123
  Env:     dev
  Status:  ✓ connected, 8 secrets available

Allowlist (5 domains):
  • api.github.com
  • api.stripe.com
  • slack.com

Credentials (3 configured):
  • api.github.com     Authorization: ✓ loaded
  • api.stripe.com     Authorization: ✓ loaded
  • slack.com          Authorization: ✓ loaded
```

---

## Security model

| Threat | Mitigation |
|---|---|
| Agent reads secrets from context | Secrets in Infisical — never in agent context or disk |
| Agent exfiltrates credential via API | Domain allowlist — 403 for anything not listed |
| Agent sets its own auth header (MCP) | Explicitly rejected with error |
| Runaway agent burns API credits | Per-domain rate limit — configurable 429 |
| Prompt injection causes looping | Loop detection + X-Aegis-Warning header |
| Audit trail | NDJSON log — every request recorded, values never logged |
| Secret rotation | Infisical secrets refresh every 5 min — rotations propagate automatically |

---

## Self-hosting Infisical

Infisical is MIT-licensed and fully self-hostable. Point Aegis at your own instance:

```yaml
infisical:
  site_url: https://secrets.your-company.com
  project_id: your-project-id
  environment: dev
```

No data ever leaves your infrastructure.

---

## Troubleshooting

### MCP fails with `spawn ... ENOENT`

Your MCP `command` path is wrong. Point to an existing binary:

```json
{
  "mcpServers": {
    "aegis": {
      "command": "/path/to/aegis/dist/aegis-darwin-arm64",
      "args": ["-mode", "mcp", "-config", "/path/to/project/aegis.yaml"]
    }
  }
}
```

### `no aegis.yaml found`

Either create one:

```bash
aegis init -services openai
```

Or pass an explicit path with `-config /absolute/path/to/aegis.yaml`.

### Infisical: `Project with ID ... not found`

`project_id` must be the actual Infisical **Project ID** (UUID-like), not slug/name.
Get it from Infisical Project Settings.

### Infisical: `You are not a member of this project`

Assign your Machine Identity to the project and grant read access for the target environment/path.

### Infisical configured but startup fails

This is expected in strict mode. When `infisical:` is configured, Aegis fails closed if Infisical auth/secret load fails.
`.env` fallback is only used when `infisical:` is not configured.

### Verify setup quickly

```bash
aegis status
```

Look for:

- `Status: ✓ connected, ... secrets available`
- `Credentials ... Authorization: ✓ loaded`

---

## License

Apache 2.0

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yagna-1](https://github.com/yagna-1)
- **Source:** [yagna-1/aegis](https://github.com/yagna-1/aegis)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yagna-1-aegis
- Seller: https://agentstack.voostack.com/s/yagna-1
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.