Deployment
One binary and one directory: run it as a CLI job, as the web console in one container, or in a cloud with Terraform and Helm.
There is no external database to run. All state is one directory: a workspace's .ekos/, or the EKOS home (~/.ekos, /var/lib/ekos in the image) holding every project's config and compiled data, the console's database and run logs. Three shapes:
| Shape | What runs | For |
|---|---|---|
| CLI | ekos build … commit as a job, ekos mcp serve beside it |
one person, CI |
| Console | the image — the ekos binary, the console API and UI on port 8000 — with the home as one volume |
a team: tenants, roles, scheduled runs, agents through one gateway |
| Cloud | the same image, deployed by deploy/terraform or the Helm chart deploy/helm/ekos (RFC 0232) |
a team, on Azure, Google Cloud or AWS |
CLI on one host
| Role | Command | Writes? |
|---|---|---|
| Indexer | ekos build … commit on a schedule or on change |
yes |
| Server | ekos mcp serve (stdio, --tcp, or --http) |
no (except the two review tools) |
# indexer (cron / CI)
ekos build && ekos recover && ekos resolve --force && ekos compile && ekos commit --yes
# server for URL-only clients, behind a TLS reverse proxy
ekos mcp serve --workspace /srv/ekos/workspace --http 127.0.0.1:8080 --token-file /etc/ekos/mcp.token
A project can live in the home instead of beside its sources (RFC 0178): ekos project add shop --source /srv/repos/shop, then ekos --project shop build and so on. The sources are never written to.
The console in one container
The production image is the repository's root Dockerfile; deploy/docker-compose.yml runs it. Tagged releases publish ghcr.io/alexeyban/ekos:<version>; --build builds it from a checkout (several minutes).
cp deploy/.env.example deploy/.env # sources dir, session secret, OIDC issuer/client, owners, EKOS_CONSOLE_PRODUCTION=true
docker compose -f deploy/docker-compose.yml up -d --build
- Sources are mounted read-only at
/sources; an owner sets which directories each tenant may use. - Sign-in is any OIDC provider; EKOS stores no passwords.
EKOS_CONSOLE_PRODUCTION=truerefuses to start without OIDC, an owner and a session secret, and turns the development tokens off. - The container speaks plain HTTP on
127.0.0.1:8000: put a TLS reverse proxy in front, and do not bind0.0.0.0. - A server without internet access:
docker savethe image on a connected machine anddocker loadit on the server. - The image is
linux/amd64, built with theobject-storagefeature (backups to S3, Azure Blob, Google Cloud Storage); it has neither theoracledriver feature nordistributed.
Without Docker, the full install package runs the same console from its own bundled Python: ekos setup opens a wizard in the browser, ekos setup --answers answers.toml applies the same answers without one, and can install a login service (a systemd user unit on Linux). For one person, mode = "local" serves the console on loopback only with a one-time sign-in code (ekos console open). ekos uninstall removes what setup installed and keeps the home unless --purge.
The full operator's guide — tenants, roles, projects, databases, agents, model credentials, backups — is docs/deployment.md in the repository.
In a cloud (RFC 0232)
deploy/terraform deploys the image to three clouds, three ways each:
compute |
Azure | Google Cloud | AWS |
|---|---|---|---|
vm |
VM + managed disk, Caddy | Compute Engine + persistent disk, Caddy | EC2 + EBS, Caddy |
container |
Container Apps + Azure Files NFS | Cloud Run + Filestore | ECS Fargate + ALB + EFS |
kubernetes |
AKS + Helm chart | GKE Autopilot + Helm chart | EKS Auto Mode + Helm chart |
cd deploy/terraform/examples/azure # or gcp, aws
cp terraform.tfvars.example terraform.tfvars # compute, OIDC, owners, repositories
export TF_VAR_secrets='{"OPENAI_API_KEY":"…"}' TF_VAR_git_token=… TF_VAR_oidc_client_secret=…
terraform init && terraform apply
terraform output url
What every deployment does:
- Secrets live in Key Vault, Secret Manager or Secrets Manager, never in the image or the repository. The platform injects them, or mounts them as files the image's entrypoint turns into variables.
- One workload identity may read those secrets and write the backup prefix — nothing else. A private Azure registry (
acr_id) is pulled with that identity; no registry password exists. - Sign-in: give
oidcandownersand the console starts in production mode. Without OIDC it uses two generated tokens (terraform output -json static_tokens). - Sources come from git:
git_repos = ["shop=https://github.com/acme/shop.git#main"]runs a git sync beside the console that clones into/sources/shopand follows the branch every five minutes. - Backups run every night (
backup_cron, UTC) to the deployment's bucket and expire afterbackup_retention_days. - A new deployment over an existing bucket restores itself: a console that starts over an empty home restores the newest backup before it opens its database. An empty location means a first deployment; any other failure stops the start, so a console that cannot read its backups never starts empty and overwrites them. A home too large for the platform's start allowance is restored once by hand instead (
EKOS_CONSOLE_BACKUP_RESTORE_ON_EMPTY=false). - One console at a time: an instance lease over the shared home makes a new revision take over and the old one stop. A platform that restarts the stopped console finds it standing by, not taking the lease back. Never run more than one replica — the Helm chart runs one, with the
Recreatestrategy. exposure = "private"keeps the console's address inside the network (not available forvm). On GKE and EKS adomaingets an HTTPS ingress preset; on AKS you give the ingress class and TLS inhelm_values.
The image. The modules and the chart default to the latest release, ghcr.io/alexeyban/ekos:1.1.0, which predates RFC 0232: it has no entrypoint, no git sync, no ekos home backup --to, no instance lease and no secrets read from files. Until a release contains them, build the image from main and set image.
What has been applied for real. Azure with compute = "vm" (2026-10-31, through Azure Pipelines, image from a private registry): HTTPS from Let's Encrypt, Key Vault secrets, git sync, a project compiled from the console, a backup to Blob Storage in 4 s and a restore on first start in 12 s; then everything was destroyed. Azure with compute = "container" (Container Apps, 2026-11-01): HTTPS, sign-in, a project configured in the browser, a backup in 8 s and the compile worked; the run found the lease livelock during a revision rollout, ignore-patterns file names that recover did not honour, a 500 on a slow knowledge server and an apply-time provider rule — all fixed. Google Cloud, AWS and Azure kubernetes have not been applied yet: they are checked with terraform validate, terraform test with mocked providers, and helm lint / helm template; the image's backup, restore, git sync and first-start restore were tested against MinIO.
What it costs, as list prices for the module defaults in the examples' regions, one console all month, light traffic, 10 GB of backups (checked 2026-10-31; estimates, not quotes — excluding egress, model calls, DNS, taxes):
compute |
Azure | Google Cloud | AWS |
|---|---|---|---|
vm |
~$205 | ~$150 | ~$200 |
container |
$115–280 | $330–375 | ~$145 |
kubernetes |
~$235 | $145–155 | $180–195 |
Disk speed matters for large commits: see Storage.
Larger scale
Partitioned storage (single machine) and distributed mode (coordinator + compile workers + query workers + gateway, optionally with S3-compatible object storage) are covered in Storage and Operations → Storage. Build with --features distributed for object-store reads. The console does not use distributed mode: it is one writer over one home.