Deployment topology
This page lists the hosts by role, the CapRover and swarm layout on the core host, the networks, the published ports and why each is published or not, and the ECR images.
The source documents call hosts app-01 to app-04. Those are labels from the infrastructure repository (hostinger). Addresses, tailnet names and domains are deliberately not reproduced here.
Hosts by role
| Role | Source label | State | What runs there |
|---|---|---|---|
| Core host | app-03 | Live | A second, independent single-node CapRover (own catalog file, own drift gate arguments): Postgres, gateway, core session worker, API |
| Temporal host | app-01 | Live, shared with four other products | The shared Temporal cluster (temporalio/auto-setup:1.23.1.1), namespace agentforge-prod with 168 h retention. No TLS or auth; tailnet ACL only |
| Throwaway test host | app-02 | Torn down 2026-11-13 | The earlier throwaway session-path test. Crowded production host; AgentForge was removed |
| Spare core host | app-04 | Not built | A further 4 vCPU host that "may take AgentForge later by re-pointing the same entries" (ADR 0004) |
| Exec host (sandbox host) | none | Not built | Needed for CodeCrucible and any non-local sandbox work: Linux, Docker, verified runsc, a tailnet grant to Temporal only (precondition PRE-1) |
| Laptop and VPS fleet workers | none | Built, cannot reach the gateway yet | macOS OrbStack or Linux containers running apps/worker target exec |
Why a dedicated core host (ADR 0004): app-02 was crowded, and sharing a host with a public-facing product was rejected for blast radius because AgentForge holds the model key and runs model-driven code. Decision date: 2026-11-14/15, accepted by the owner. Rejected alternatives: deploy on app-02 as first planned, compose plus ansible outside the catalog (a second deploy method), and sharing app-03 with another product.
CapRover and swarm layout on the core host
All four services are CapRover apps of type worker (the API is a worker-type app with a published port and no domain), one instance each (instance_count: 1). Service names resolve on the private overlay by Swarm service name, for example agentforge-postgres:5432, unless an opt-in network_aliases feature is used (hostinger draft PR #80 at the time of the 2026-11-13 findings; whether it merged is unverified).
| Service | Image repo | Entry | Replicas | Port(s) | Published |
|---|---|---|---|---|---|
agentforge-postgres | portfolio/agentforge-postgres (mirror of postgres:16 by digest) | upstream image | 1 | 5432 | no |
agentforge-gateway | portfolio/agentforge-gateway | node dist/server.js | 1 (state is in memory) | data 8787, control 8788 | none at launch (ADR 0005) |
agentforge-worker | portfolio/agentforge-worker | node dist/main.js (default Dockerfile stage) | 1 | none (liveness by process only) | no |
agentforge-api | portfolio/agentforge-api | node dist/server.js | 1 (rate limits and semaphore are in memory) | container 3000 | host port 3100, tailnet reachable |
Replica rules, from the runbooks:
- API: replicas must stay at 1. The rate limits, the auth-failure throttle,
MAX_CONCURRENCYand the in-flight abort set live in process memory. A second replica doubles every limit. Spend caps are in Postgres and stay correct. - Gateway: replicas must stay at 1. Registrations, job tokens, subject tokens, rate windows and the per-call
settleCallguards are in memory. A restart drops them all and fails closed (401 until callers re-register; unsettled debits stay at the worst case). - Worker: replicas 1 on the core host. Turn concurrency is
WORKER_CONCURRENCY(default 2).
Stop grace periods the runbooks ask for:
| Service | Minimum stop grace | Derivation |
|---|---|---|
| API | 10 s | SHUTDOWN_GRACE_MS (default 8000) plus 2 s |
| Gateway | 12 s | GATEWAY_SHUTDOWN_GRACE_MS (default 10000) plus 2 s |
| Worker | 8 s | WORKER_SHUTDOWN_GRACE_MS (default 5000) plus ABORT_GRACE_MS (1 s) plus 2 s |
Container hardening common to the images: non-root user (uid 10001 for the swarm secret match, see Secrets flow), PID 1 is tini, /app read-only, and a Docker HEALTHCHECK. The API healthcheck fetches http://127.0.0.1:$PORT/health every 10 s (timeout 3 s, start period 20 s). Worker images use a process liveness check every 30 s.
Networks
agentforge-netis an encrypted, attachable overlay the apps role creates if missing. An--internalnetwork has to be created by hand first (owner step).- The
networks:list in the catalog is the complete attachment list written toTaskTemplate.Networks. Services that nginx must reach listcaptain-overlay-networkplus the private net; private services list only the private net. The API keeps both in the design; the live attachment of the API is not recorded in the dossiers (Unverified). - The gateway is on
agentforge-netonly. This is a precondition forGATEWAY_CONTROL_BIND_ANY=private-network-only: the control listener binds0.0.0.0(the image has no default forGATEWAY_CONTROL_HOST), which is safe only when the gateway sits on the private overlay alone. - The core host is a single swarm node, so isolation (not encryption) is the control between services on it.
Published ports and why
| Port | Service | Published | Reason |
|---|---|---|---|
| 3000 (host 3100) | API | yes, tailnet reachable, no public domain | Clients reach the API directly over the tailnet. TLS and a public domain are not set up |
| 8787 | Gateway data listener | no at launch | A published swarm port joins the shared ingress overlay, which would expose 8788 to every other published service (ADR 0005) |
| 8788 | Gateway control listener | never | Control tokens are the second barrier, not the first |
| 5432 | Postgres | no | Reached by service name on agentforge-net |
| 7233 | Temporal (remote) | on the Temporal host, tailnet only | A ufw rule allows it on the tailscale interface only |
The gateway decision in detail:
The fix path (design option A, docs/design-gateway-fleet-exposure.md), all steps still open except step 1:
- Gateway setting
GATEWAY_CONTROL_BIND_CIDR: coded onmain(commit1da8928), not released. - Hostinger pins the
agentforge-netsubnet to a known value. - Catalog PR: re-add
published_portsfor 8787 on the gateway only; dropGATEWAY_CONTROL_BIND_ANYandGATEWAY_CONTROL_HOSTfrom the SSM set; addGATEWAY_CONTROL_BIND_CIDR. - Tailnet ACL grant from the worker tag to the core host tag on
tcp:8787, plus the ufw tailnet route allow for 8787 (the owner's action). - Fleet worker
GATEWAY_URLas plain http over the tailnet, with that exact host inGATEWAY_HTTP_ALLOWED_HOSTS.
The release tag that carries step 1 was declined by the owner on 2026-11-16 (wait until more of the quality work is done).
Tailnet access rules
| Source | Destination | Port | State |
|---|---|---|---|
Worker tag (tag:agentforge-worker) | Temporal host | 7233 | ACL applied by the owner 2026-11-13, one grant, no wildcard rules. Not read back by an agent |
| Worker tag | Core host | 8787 | Not granted; waits for the CIDR design |
| Application-host containers | Temporal host | 7233 | Measured open from the throwaway host on 2026-11-13 (host, captain-overlay container, default-bridge container): no ufw, ACL or route change was needed. The core host reached Temporal in the smoke runs |
Temporal 1.23 OSS cannot restrict by task queue. A fleet host that reaches 7233 can poll any queue of any namespace and fail its tasks (risk R-5). The ACL is the only control until Temporal auth is enabled. The worker tag can therefore reach all namespaces of the shared cluster; payloads stay protected by the application codec (TEMPORAL_PAYLOAD_KEYS). This is ADR 0003 (dossier 2026-11-13).
ECR images
| Repository | Content | Pushed by | Tags that exist |
|---|---|---|---|
portfolio/agentforge-api | apps/api/Dockerfile | docker-release on a tag push | v0.1.0, v0.2.0 |
portfolio/agentforge-gateway | apps/gateway/Dockerfile, baked /policies, empty /registry | same | v0.1.0, v0.2.0 |
portfolio/agentforge-worker | apps/worker/Dockerfile, default stage (session worker) | same | v0.1.0, v0.2.0 |
portfolio/agentforge-postgres | mirror of postgres:16 pinned by digest | docker-release manual dispatch, mirror job | v0.1.1 (plus an unused index-wrapped v0.1.0) |
portfolio/agentforge-temporal | mirror of temporalio/auto-setup:1.23.1.1 | same | v0.1.1 (plus an unused index-wrapped v0.1.0); not used on the core host, which uses the shared cluster |
Not released through the workflow: the Dockerfile targets exec (fleet exec worker), factory, quality-exec, the sandbox image apps/sandbox-runner and the quality image apps/worker/quality-image. The exec image is built locally on each laptop (docker build -f apps/worker/Dockerfile --target exec). Builds are linux/amd64, no provenance, no SBOM, no latest tag.
The ECR repositories are immutable and have a lifecycle policy with a v prefix rule. The registry account and region are not reproduced here.
Release v0.2.0 ran as workflow run 43744340182. Its first attempt pushed the worker and failed on the api and gateway with no space left on device; only the two failed jobs were re-run. That incident produced the 20 GB preflight guard described in Release process.
Host-level facts that matter
- Docker publishes on
127.0.0.1only on a sandbox host: withoutgateway_mode_ipv4=isolated, a port published on0.0.0.0is reachable from an--internalnetwork (docs/deploy-sandbox.md, probe 0l). - The gateway on a sandbox host runs with
net.ipv4.ip_forward=0andnet.ipv4.conf.all.forwarding=0. The production deploy has to reproduce both sysctls and check them (cat /proc/sys/net/ipv4/ip_forward /proc/sys/net/ipv4/conf/all/forwardingprints0 0). The driver does not set them. - The
captain-overlay-networkis shared by about 65 production apps and is unencrypted. This is why the production requirement is a dedicated overlay.
Unverified
- Tailnet-inbound access to a published port on the core host (a stale ufw route-deny blocked it on the test, and Docker's anti-spoof rule blocked a shared overlay on the throwaway host).
- Interface naming and ordering inside a swarm task with several networks.
- Whether CapRover accepts a pinned
agentforge-netsubnet. - MagicDNS inside OrbStack containers (use the tailnet address if it fails).
runscanywhere (spike S3), and any real exec host.
Sources
docs/sessions/2026-11-15-app03-deploy-and-smoke/ARCHITECTURE.md,README.md,SUMMARY.md,LESSONS.mddocs/sessions/2026-11-15-app03-deploy-and-smoke/adr/0004-app03-dedicated-agentforge-host.md,0005-gateway-publishes-no-port-at-launch.md,0006-postgres-persistent-volume.mddocs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/adr/0003-temporal-acl-only-and-baked-gateway-policy.mddocs/design-gateway-fleet-exposure.mddocs/deploy-app02-test.md(services, images, networks sections)docs/deploy-api-coolify.md,docs/deploy-gateway-coolify.md,docs/deploy-worker-coolify.md,docs/deploy-worker-fleet.md,docs/deploy-sandbox.mddocs/p2-findings.md("App-02 test deployment", "Production deploy: answers from the fleet sessions", "Temporal route app-02 -> app-01: measured", "App-03 production deploy and smoke test")apps/api/Dockerfile,apps/gateway/Dockerfile,apps/worker/Dockerfile.github/workflows/docker-release.ymlsecrets.manifest.yml