Documentation

Everything needed to run aegis. For putting it behind a reverse proxy, see the deployment guide. The full specification lives in spezifikation.md; where the two disagree, the spec wins.

Quick start

docker run -d --name aegis -p 2019:2019 \
  -v "$PWD/config.yaml:/etc/aegis/config.yaml:ro" \
  -e AEGIS_PUBLIC_URL=https://aegis.example.com \
  --read-only --cap-drop ALL \
  ghcr.io/andreaskasper/aegis:latest

Or with Compose:

services:
  aegis:
    image: ghcr.io/andreaskasper/aegis:latest
    ports: ["2019:2019"]
    volumes:
      - ./config.yaml:/etc/aegis/config.yaml:ro
    environment:
      AEGIS_PUBLIC_URL: https://aegis.example.com
    read_only: true
    cap_drop: [ALL]
    restart: unless-stopped

Then point an MCP client at https://aegis.example.com/mcp. The client discovers the OAuth endpoints, registers itself, and opens the login page in a browser.

Building from source instead:

git clone https://github.com/andreaskasper/aegis
cd aegis/src
go build -o aegis .
AEGIS_CONFIG=../config.yaml AEGIS_PUBLIC_URL=http://localhost:2019 ./aegis

Configuration

One YAML file holds everything. Users are the top-level unit: each user brings its own secrets and its own targets, so what a user can do is answerable by reading one contiguous block.

server:
  listen: ":2019"
  public_url: "https://aegis.example.com"   # required
  max_response_bytes: 1048576               # 1 MiB
  request_timeout: "30s"
  token_ttl: "12h"
  code_ttl: "60s"
  login_rate_limit: "10/m"                  # per source IP

users:
  - name: andreas
    password: "bcrypt:$2a$12$..."
    allow_any: false

    secrets:
      lexware_token: "env:LEXWARE_TOKEN"
      github_pat: "file:/run/secrets/github_pat"

    targets:
      - id: lexware
        description: "Lexware Office accounting API"
        base_url: "https://api.lexware.io"
        methods: [GET, POST]
        paths: ["/v1/**"]
        rate_limit: "60/m"
        inject:
          headers:
            Authorization: "Bearer ${lexware_token}"

Server

Users

Value prefixes

Every secret value, and every password, may be literal or a reference. Resolution happens once at load time — an unresolvable reference is a configuration error, not a runtime surprise.

Targets

A target is a permitted destination. The first target whose scheme, host, port and path pattern accept a URL wins; the method is checked afterwards, so the audit log can name the target that was attempted.

Path patterns

Matching is case-sensitive and runs on the decoded, cleaned path. A request path containing .. is rejected before matching, so traversal cannot launder a URL into a narrower pattern.

Injection

Injection rules are attached to the target, never chosen by the model. Values may contain ${secret_name}; $${ is a literal ${.

inject:
  headers:
    Authorization: "Bearer ${token}"      # set, overwriting the model
  query:
    appid: "${api_key}"                   # set on the final URL
  body:
    "$.auth.token": "${token}"            # JSON bodies only

Body injection applies only when the request body parses as JSON and the content type is JSON; otherwise the request is refused with body_injection_failed. Intermediate objects on the path are created as needed.

Reloading

Aegis watches the config file and reloads on change; SIGHUP forces it. If the new file does not parse or does not validate, the previous configuration stays active and one error line is logged. Existing sessions survive a reload — which matters, because a restart logs everyone out.

docker kill -s HUP aegis

A removed user invalidates its tokens on their next use. Target changes take effect on the next request.

Authentication

Aegis is its own OAuth 2.1 authorization server, so a compliant MCP client needs nothing but the URL.

There is no consent screen: a successful login issues a token scoped to that user's targets. The token is the identity — it decides what is reachable and which secrets are attached.

Tools

list_targets

No arguments. Returns the targets the calling user may reach. Injection rules, secret names and secret values are not part of the response.

{
  "targets": [
    {
      "id": "github",
      "description": "GitHub REST API, read-only",
      "base_url": "https://api.github.com",
      "methods": ["GET"],
      "paths": ["/repos/andreaskasper/**", "/user"],
      "rate_limit": "120/m"
    }
  ],
  "allow_any": false
}

http_request

An upstream 4xx or 5xx is a successful tool call — the status is reported rather than raised. Only aegis-side refusals are errors.

{
  "status": 200,
  "headers": {"content-type": "application/json"},
  "body": "...",
  "truncated": false,
  "target": "github",
  "duration_ms": 143
}

Headers the model may not set

Authorization, Proxy-Authorization, Cookie, Host, Content-Length, Connection, Transfer-Encoding, Upgrade, X-Forwarded-*, X-Real-IP — plus any header the matched target injects. A header value containing a line break is refused too.

Request pipeline

Ordered. Any step may end the request.

Redaction runs before truncation, so a secret cannot survive by straddling the cut. Set-Cookie is dropped entirely and never reaches the model.

Errors

Aegis-side refusals come back as a tool error with a stable code:

{
  "error": "no_target",
  "message": "No permitted target matches this URL. Call list_targets to see what is available.",
  "status": 403
}

Audit log

One JSON object per line on stdout, for every request — allowed or refused.

{"ts":"2026-07-28T21:14:02.183Z","level":"info","event":"request",
 "user":"andreas","client_id":"aBc123","target":"github",
 "method":"GET","url":"https://api.github.com/user","status":200,
 "duration_ms":143,"bytes":312,"truncated":false,
 "injected":["github_pat"],"redacted":0}

injected lists secret names only. Any query parameter the target injects is written as [REDACTED] in the logged URL. Request and response bodies are never logged, at any level.

A non-zero redacted count is worth attention: it means the upstream reflected one of your credentials back, and redaction caught it.

Other events: startup, shutdown, config_reloaded, config_error, short_secret, login_success, login_failed, client_registered, token_issued, token_reuse_detected.

CLI

$ aegis validate config.yaml
config.yaml: OK
  public_url: https://aegis.example.com
  listen:     :2019

  user andreas (allow_any=false)
    secrets: github_pat, lexware_token
    target lexware   GET,POST https://api.lexware.io  paths=/v1/**
    target github    GET https://api.github.com  paths=/repos/andreaskasper/**,/user

Environment

Any variable referenced by an env: value in the config must be present in the container's environment as well.