Reference
Architecture
What runs in your account, what each part does, and how the parts talk.
eode runs as two always-on workloads, one engine per active user, and four AWS services.
Workloads
All of them come from two images, eode-app and eode-engine.
| Workload | Namespace | Port | Health | What it does |
|---|---|---|---|---|
eode-app | eode | 8787 | GET /api/health | The web app and its API. Signs users in, runs RIA's conversations, starts and stops engines |
eode-mcp | eode | 8848 | GET /healthz, MCP at /mcp | The MCP endpoint. Checks the caller's token, then works on that user's engine |
| Engines | eode-engines | 50051 | — | One per active user, created on demand, removed after 30 idle minutes |
eode-migrate | eode | — | exits 0 | Applies database changes before each install and upgrade. The only workload that can read the database owner login |
eode-app can create and delete Deployments and Services in eode-engines, and nowhere else. Engines run only on
the engine node group, sized by the model they hold (12, 24 or 48 GiB of memory by default; set by EngineMemoryClasses), and need about half a CPU
each. Every engine and eode-app share the same EFS file system, where models are kept.
What the stack creates
| Nested stack | Creates |
|---|---|
| Network | A VPC across 2 or 3 availability zones with public and private subnets and NAT, or nothing (existing VPC) |
| Cluster | Amazon EKS with a general node group and a tainted engine node group, Pod Identity, and the EFS CSI add-on |
| Data | RDS PostgreSQL 16 (private, encrypted, automated backups), ElastiCache Redis (TLS + AUTH), EFS with an access point |
| Secrets | The eode/* secrets in Secrets Manager, generated where nobody needs to know them, and the IAM roles each workload uses |
| Installer | A CodeBuild project that installs the gateway, cert-manager and the secrets driver, prepares the database, installs eode, and checks its health |