Architecture¶
Image graph¶
debian:trixie-slim
│
┌──────▼──────┐
│ base │ Node 26 · Python 3 · git/gh · Chromium
│ │ Claude Code · OpenCode · Multica CLI
└──────┬──────┘
┌──────────┬───────┼────────┬─────────┬──────────┬────────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼
node python php go flutter devops qa
│
└──────────────► design (adds Penpot MCP + Xvfb)
autoscaler ← FROM base + AWS CLI + Docker CLI
All variant images are built from base, so a base-layer change is one rebuild
and every variant picks it up. The base image is published first; variants use
BASE_IMAGE to point at either the local tag or the registry tag.
Build pipeline¶
versions.env is the single source of truth. scripts/build.sh reads it, exports
every key, and passes each one as a --build-arg. Dockerfile ARGs have no
defaults, so a build that forgets a version fails immediately instead of
producing an unpinned image. scripts/check-versions.sh enforces this in CI.
Downloads are checksum-verified wherever upstream publishes a checksum:
- Node tarball (
SHASUMS256.txt) - GitHub CLI, Multica CLI (release
checksums.txt) - Terraform (
SHA256SUMS), kubectl (.sha256), Helm (.sha256sum) - Docker Compose, uv, k6, golangci-lint
- Composer installer (signature)
Go's .sha256 URL does not exist; the checksum comes from the JSON release
manifest at https://go.dev/dl/?mode=json&include=all.
What happens at container start¶
tini
└─ variant entrypoint (php: databases; design: Xvfb + MCP)
└─ /usr/local/bin/multica-entrypoint
1. validate MULTICA_TOKEN
2. resolve AI_* → ANTHROPIC_* (native wins)
3. derive model tiers
4. configure Claude Code (CLAUDE_CONFIG_DIR on /workspaces)
5. configure OpenCode (probe /v1/models, write 0600 config)
6. configure Codex (CODEX_HOME on /workspaces, config.toml)
7. run variant hooks (design: register Penpot MCP)
8. configure git / gh (optional)
9. print banner (no secrets)
10. multica login --token
11. exec multica daemon start --foreground
The daemon is the foreground process. tini forwards SIGTERM; the daemon
deregisters its runtimes and exits. stop_grace_period: 90s gives a running task
time to finish.
If you set MULTICA_DRY_RUN=1, execution stops after step 9.
Why the entrypoint is split¶
| File | Responsibility |
|---|---|
lib/common.sh |
logging, boolean parsing, URL helpers, hooks |
lib/config.sh |
AI_* resolution, credential style, model tiers |
lib/claude.sh |
CLAUDE_CONFIG_DIR, update/traffic policy |
lib/opencode.sh |
catalogue probe, config generation, model refs |
lib/codex.sh |
CODEX_HOME, Responses provider config |
lib/git.sh |
git identity, gh auth setup-git |
lib/banner.sh |
secret-free startup summary |
entrypoint.sh |
ordering, login, daemon |
Each concern can be read and tested on its own. Variants extend the sequence by
dropping a file into /usr/local/lib/multica/hooks/ — the design image uses this
to register the Penpot MCP server without the base image knowing what Penpot is.
Security posture¶
- Non-root. Everything runs as
runner(uid/gid 1000). The design image does not need root for Xvfb or the MCP server; the PHP databases run asrunnerwith data under/tmp. There is nogosu, nosetprivprivilege drop at runtime, and therefore no dependency on ptrace/seccomp behaviour that Fargate blocks. - No inbound port. The runtime connects out to Multica and the AI router.
- Secrets stay at runtime. No token or key is in any layer. OpenCode's config
is written at start with mode
0600. - Agent CLIs do not self-update. The image is the version.
- No Docker socket, except the optional Swarm autoscaler, which needs it to
call
docker service scale. The ECS adapter uses IAM instead.
See Security for the threat model.
Why Debian 13 (trixie-slim)¶
- Current stable at the time of writing; long support window.
- Packages the agent toolchains need (PHP 8.4, Python 3.13, Chromium, MariaDB, PostgreSQL) are available without third-party repositories.
slimkeeps the base small; anything heavy is installed explicitly.
Node comes from the official tarball rather than Debian's package, so the version is pinned exactly (24.x LTS) and not tied to the distro release.
Healthcheck¶
The image declares:
HEALTHCHECK CMD pgrep -f "multica.*daemon" >/dev/null || exit 1
It is intentionally shallow: it answers “is the daemon process alive?”, not “is the AI router healthy?”. A router outage should not restart every runtime and lose in-flight sessions. Orchestrators that ignore Docker healthchecks (ECS) get the same command in the task definition.