DEPLOY

Put Aegis on AWS, then point your IDE agent at it.

Aegis is one shaded Java jar in a container, configured by a single mounted file. The same image runs on EKS through the Helm chart, on ECS or Fargate as a task, or on an EC2 host as a plain process. Once it is listening, an AI IDE connects to it as an ordinary MCP server over HTTP, and every tool call is governed.

IMAGE

One image, built from the repository Dockerfile.

The Dockerfile builds the gateway jar on a Temurin 21 base, then runs it as a non-root user (uid 10001) with a read-only root filesystem. The only writable directory is /var/lib/aegis, where the audit journal lives. Configuration is mounted read-only at /etc/aegis/aegis.yaml. Base images are pinned by digest.

# Build and push to Amazon ECR
aws ecr create-repository --repository-name aegis-gateway
docker build -t aegis-gateway:2.0.0 .
aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin <account>.dkr.ecr.us-east-1.amazonaws.com
docker tag aegis-gateway:2.0.0 <account>.dkr.ecr.us-east-1.amazonaws.com/aegis-gateway:2.0.0
docker push <account>.dkr.ecr.us-east-1.amazonaws.com/aegis-gateway:2.0.0

Record the pushed image digest (sha256:...). The Helm chart can pin by digest, and complete-control mode requires it: a mutable tag is refused.

AWS EKS

EKS with the bundled Helm chart.

The chart is at charts/aegis. It defaults the pod to non-root, read-only root filesystem, dropped capabilities and a RuntimeDefault seccomp profile. Put the Aegis configuration under config: and name your secrets with envFrom, never inline.

# values-prod.yaml (excerpt)
image:
  repository: <account>.dkr.ecr.us-east-1.amazonaws.com/aegis-gateway
  digest: "sha256:..."          # pin by digest, not tag
envFrom:
  - secretRef: {name: aegis-secrets}   # AEGIS_SIGNING_KEY, tokens, and so on
persistence:
  size: 1Gi
  storageClassName: gp3
networkPolicy:
  enabled: true
  ingressFrom:
    - podSelector: {matchLabels: {app: agent-workloads}}
config:
  gateway: {name: aegis-prod}
  host:
    listen: {host: 0.0.0.0, port: 8080, allowPlaintext: true}  # ALB terminates TLS
  audit: {file: /var/lib/aegis/audit.jsonl}
  # ... identity, policy, sources ...
helm upgrade --install aegis charts/aegis -n aegis --create-namespace -f values-prod.yaml
kubectl -n aegis get pods
kubectl -n aegis logs deploy/aegis | Select-String listening

Expose it with an Ingress on an AWS Load Balancer Controller (ALB) that terminates TLS and adds authentication at the edge if you want, or keep it ClusterIP and reach it from agent workloads inside the cluster. For more than one replica, set sharedState: true and configure a Postgres state store, otherwise an approval granted on one pod is unknown to the next; the chart refuses replicaCount > 1 without shared state.

AWS ECS AND FARGATE

ECS or Fargate as a task.

No Kubernetes needed. Run the same ECR image as a task definition.

Task shape

One container, port 8080. Mount the config from an EFS access point or bake a ConfigMap-equivalent into the image build. Put the audit journal on an EFS volume at /var/lib/aegis so it survives task replacement.

Secrets and edge

Inject AEGIS_SIGNING_KEY and tokens from AWS Secrets Manager through the task secrets block. Front the service with an ALB that terminates TLS; set host.listen.allowPlaintext: true because TLS ends at the load balancer.

Least privilege: the task role needs only what your configured sources call (for example a scoped Secrets Manager read). Aegis never needs broad AWS permissions to govern MCP traffic.

EC2 AND OWN HOST

EC2, or any host, as a plain process.

The gateway is a single jar. On an EC2 instance with a JRE 21, this is the whole deployment:

export AEGIS_SIGNING_KEY=...        # from Secrets Manager or SSM Parameter Store
java -XX:MaxRAMPercentage=75 -jar aegis-gateway-2.0.0-all.jar --config /etc/aegis/aegis.yaml

Run it under systemd as a non-login user, keep /etc/aegis/aegis.yaml read-only, and let the audit journal write to a dedicated data directory. This own-host path is the same one the tutorials use, so a profile you proved locally moves to EC2 unchanged.

AI IDE

Connect Kiro, Cursor, VS Code or Claude Desktop.

To the IDE, Aegis is a normal MCP server reached over HTTP. Point the client at the gateway URL and present the bearer token of the person the agent acts as. Do not list auto-approved tools: let Aegis decide. Replace the URL with your ALB or service address in a cloud deployment.

Kiro and Cursor

{
  "mcpServers": {
    "aegis": {
      "url": "https://aegis.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

VS Code

{
  "inputs": [
    { "type": "promptString", "id": "aegis-token",
      "password": true, "description": "Aegis bearer token" }
  ],
  "servers": {
    "aegis": {
      "type": "http",
      "url": "https://aegis.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:aegis-token}" }
    }
  }
}

Claude Desktop and the MCP Python SDK connect the same way: the gateway URL plus a bearer token. Ready-made per-project settings for VS Code, Kiro and Cursor, including the optional Knox front door, are in the repository tutorial directory. Walk one end to end on the tutorials page.

The token identifies the caller to Aegis. Its groups decide which tool classes it may use, whether a write needs an independent approver, and what it may read. Issue a narrow token per person or per agent, not one shared admin token.

BEFORE PRODUCTION

Deployment checklist.

REFERENCE MAP

Continue in the guides.