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
Code of Conduct: Contributor Covenant
Releases: No releases published
Packages: No packages published
Tags: View 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

go install github.com/yagna-1/aegis/cmd/aegis@latest

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

# 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

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

# 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

cd ~/projects/my-agent
aegis init -services github,slack,stripe

3. Connect to Infisical (free, open source)

# 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

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

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:

{
  "mcpServers": {
    "aegis": { "command": "aegis", "args": ["-mode", "mcp"] }
  }
}

Cursor — .cursor/mcp.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

# .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:

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:

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

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

aegis status

Look for:

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

License

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
assets		assets
cmd/aegis		cmd/aegis
internal		internal
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
aegis.example.yaml		aegis.example.yaml
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Aegis

Project

The problem

The fix

Quickstart (5 minutes)

1. Install Aegis

2. Scaffold your project

3. Connect to Infisical (free, open source)

4. Add the Infisical block to aegis.yaml

5. Add your real secrets to Infisical

6. Start and verify

How secrets flow

Per-project isolation

Secret source behavior

IDE integration (MCP mode)

Proxy mode — any language

`aegis status`

Security model

Self-hosting Infisical

Troubleshooting

MCP fails with `spawn ... ENOENT`

`no aegis.yaml found`

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

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

Infisical configured but startup fails

Verify setup quickly

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Aegis

Project

The problem

The fix

Quickstart (5 minutes)

1. Install Aegis

2. Scaffold your project

3. Connect to Infisical (free, open source)

4. Add the Infisical block to aegis.yaml

5. Add your real secrets to Infisical

6. Start and verify

How secrets flow

Per-project isolation

Secret source behavior

IDE integration (MCP mode)

Proxy mode — any language

aegis status

Security model

Self-hosting Infisical

Troubleshooting

MCP fails with spawn ... ENOENT

no aegis.yaml found

Infisical: Project with ID ... not found

Infisical: You are not a member of this project

Infisical configured but startup fails

Verify setup quickly

License

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`aegis status`

MCP fails with `spawn ... ENOENT`

`no aegis.yaml found`

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

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

Packages