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.
- Image pinned by digest, pushed to a private registry, scanned in your pipeline.
- TLS terminated at the load balancer or by a mounted keystore; no plaintext public listener without
allowPlaintextset deliberately. - Secrets from Secrets Manager, SSM or a vault through
envFromor task secrets, never in the config file. - Durable state (Postgres) and
sharedStateset before scaling past one replica. - Network policy or security groups allow only agent workloads to reach the gateway, and allow the gateway only its reviewed egress destinations.
- Audit journal on durable storage; forward checkpoints to a SIEM or object-lock bucket the gateway host cannot rewrite.
- Narrow per-caller tokens; approver groups for destructive tools.
REFERENCE MAP