feat: prebuilt images + pull-only hosted compose + unattended cloud-init first boot — the gate for every one-click / marketplace channel

[vybe]

Summary

Publish prebuilt Trinity images (platform services and the agent base image) to a public registry on every release, ship a pull-only hosted compose file, and make first boot fully unattended from cloud-init — so a fresh VM comes up serving Trinity in ~2 minutes with no on-box builds. This is the prerequisite for every one-click / marketplace channel (DigitalOcean, Vultr, Hostinger, Elestio, Dokploy, and the #835 Packer image).

Context

Today scripts/deploy/start.sh builds the agent base image on the host (scripts/deploy/build-base-image.sh → docker/base-image/Dockerfile, 5–10 minutes) and docker-compose.prod.yml uses build: blocks — no workflow pushes images to a registry. A marketplace 1-click that spends ten minutes compiling on first boot fails the "one click" bar, and managed hosts (Elestio) and template catalogs (Dokploy/Coolify/Hostinger Docker Manager) only accept pull-only compose files.

Findings from the 2026-08-18 hosting-channels research: every VM marketplace already ships Docker-socket-mounting apps (Coolify, CapRover, Dokku, OpenClaw), so Trinity's shape is accepted; the only blocker is packaging. #835 (Packer image for GCP + Hetzner) becomes thin once images are prebuilt — its "clone to /opt/trinity and build" acceptance criteria should be revisited to depend on this issue.

Acceptance Criteria

• A release workflow publishes versioned + latest images for backend, frontend, mcp-server, scheduler and the agent base image to a public registry (e.g. GHCR); multi-arch (amd64 required, arm64 desirable — Hetzner CAX / Umbrel).
• A docker-compose.hosted.yml (name TBD) pulls those images only — no build: blocks — and works with the same .env contract as docker-compose.prod.yml.
• start.sh --unattended (or the hosted compose) never asks for input: SECRET_KEY/INTERNAL_API_SECRET/ADMIN_PASSWORD auto-generated when absent and printed once; the setup form is never reachable unauthenticated on a public IP (either the admin exists at boot or the form is bound to a one-time token).
• A cloud-init user-data example (extend trinity-ops-public/provision/cloud-init.sh) takes admin password / domain / optional Cloudflare Tunnel token and results in a serving instance; documented in docs/DEPLOYMENT.md.
• TLS story for a bare VM without a tunnel is decided and documented (Caddy sidecar or documented tunnel-only) — no HTTP-only default on a public IP without a stated warning.
• Minimum size stated wherever the hosted compose is documented: 8 GB RAM.
• docs/AGENT_INSTALL_GUIDE.md and docs/DEPLOYMENT.md reference the pull-only path as the default for servers.

Technical Notes

• Image pulls also fix the "fresh install races the base-image build" class of first-boot problems.
• Keep docker-compose.yml (dev, build-from-source) unchanged; the hosted file is additive.
• Downstream: One-click VM image for Trinity deployment (GCP + Hetzner) #835 (Packer), DigitalOcean/Vultr marketplace listings, Deploy-on-Hostinger button, Dokploy template — filed as siblings under Epic: Starter ops/DevOps agents — one-click Trinity instance management onboarding #1215.

[obasilakis]

Scoping notes from 2026-08-21/24 — TLS decision settled, AC3 partly already shipped

AC5 (TLS story) is decided: Caddy + Let's Encrypt IP certificate, no domain required

Both facts verified first-hand:

1. Let's Encrypt IP-address certificates are GA (2026-01-15) — ACME shortlived profile, ~6-day validity, http-01/tls-alpn-01 only (no DNS-01). https://letsencrypt.org/2025/07/01/issuing-our-first-ip-address-certificate/
2. DigitalOcean builds its own 1-Clicks exactly this way — digitalocean/droplet-1-clicks, .github/agents/1-click-agent.md rule 10 mandates Caddy + issuer acme + profile shortlived for any app with an HTTP interface.

So the hosted stack comes up on browser-trusted HTTPS at its bare IP with zero user input. This supersedes the earlier "bring a domain or accept HTTP" framing: a domain becomes a post-login upgrade (longer-lived cert, memorable URL), not a prerequisite. Cloudflare Tunnel is explicitly not a v1 path — a named tunnel requires owning a domain and moving its nameservers to Cloudflare, i.e. strictly more setup than the Caddy path, and the account-free Quick Tunnel variant is documented "testing and development only", caps at 200 concurrent requests and has no SSE support, which breaks Workspace streaming (GET /api/executions/{id}/stream).

AC3, first clause: already shipped

scripts/deploy/start.sh already implements --unattended / TRINITY_UNATTENDED=1 (#39/#443). It auto-generates SECRET_KEY, INTERNAL_API_SECRET, CREDENTIAL_ENCRYPTION_KEY, AGENT_AUTH_SECRET and ADMIN_PASSWORD when blank, and prints the generated admin password in the closing summary. The issue body is stale on this point — no new work needed.

AC3, second clause: this is a real, unfiled security defect

"The setup form is never reachable unauthenticated on a public IP" is not satisfied today, and the cause is not the missing token.

On a fresh install setup_completed is left false permanently, even though ADMIN_PASSWORD created a real admin at boot. init_database() runs run_all_migrations twice and then _ensure_admin_user; on the second pass setup_completed_backfill finds users still empty, does nothing, and is recorded as applied — so it never runs again. POST /api/setup/admin-password gates only on that flag, requires no auth, and calls db.update_user_password("admin", …), which overwrites the existing admin's hash. docker-compose.prod.yml publishes 8000:8000.

Net effect: on any public-IP install, whoever reaches the box first can set the admin password and own it.

The fix is to make the flag honest (an admin row with a password hash means setup is complete) — it does not overturn trinity-enterprise#49's deliberate removal of the setup token, because the admin genuinely does exist at boot; only the flag lies. Recommend filing as its own P1 bug: it affects every existing public-IP install, not just the hosted path, and should not land buried in a packaging PR.

AC2 was at risk and is not — VITE_API_URL is inert

docker/frontend/Dockerfile.prod declares ARG VITE_API_URL (default http://localhost:8000) and bakes it into the image, which would make a prebuilt frontend unusable on a remote host. It is dead: no source file under src/frontend/src reads it — the only occurrence is a comment warning against it (#722). src/frontend/nginx.conf already proxies /api/, /a2a/ and /ws to trinity-backend:8000, so the SPA uses relative URLs. The frontend image is portable across any IP or domain and is safely prebuildable.

AC1 note — agent base image name is hardcoded

trinity-agent-base:latest appears in 6+ backend locations (agent_service/lifecycle.py, system_agent_service.py, agent_service/helpers.py's trinity-agent-base:* allowlist glob) with no config knob. The hosted path should pull from GHCR and retag locally:

docker pull ghcr.io/abilityai/trinity-agent-base:vX.Y.Z
docker tag  ghcr.io/abilityai/trinity-agent-base:vX.Y.Z trinity-agent-base:latest

One line in the provisioning script, zero backend change, no invariant touched. Introducing an AGENT_BASE_IMAGE env var would mean editing that allowlist glob and the base-image drift predicate — not worth it for v1.

Work in progress

Branch feature/2280-hosted-images-unattended-boot (worktree, nothing pushed). One file written: .github/workflows/publish-images.yml — matrix over the five Trinity-built images (backend, frontend, scheduler, mcp-server, agent-base) to GHCR on v* tags plus workflow_dispatch, latest only on a real tag, GHA layer cache, build provenance args forwarded for GET /api/version. amd64 only for v1 (DO Droplets and Vultr Cloud Compute both default to amd64; the ~1.9 GB agent base image cross-builds slowly and flakily under QEMU — arm64 deferred until Hetzner CAX / Umbrel need it). Checkout is submodules: false, so the public images are OSS-only by construction rather than by an editable ignore rule.

YAML validates; untested — no tag pushed, no dispatch triggered.

docker-compose.hosted.yml not yet written, pending the Caddy service above.

Scope moved out

Detecting that an instance came from a marketplace, and showing a first-run HTTPS/VPN hardening guide, is now #2380 — a separate child of #2332. It is a product surface, not packaging.

[obasilakis]

AC3 is done — ticked. #2385 (merged 2026-08-24, closes #2381) delivered both halves:

• Secrets auto-generated, never prompted. scripts/deploy/start.sh already had ensure_hex32_secret SECRET_KEY / INTERNAL_API_SECRET; --unattended (or TRINITY_UNATTENDED=1) now also generates ADMIN_PASSWORD when blank, writes it to .env, and prints it once in the closing summary. Interactive still fails fast on a blank password rather than inventing one.
• The setup form is no longer reachable unauthenticated on a public IP — via the first branch of the AC ("the admin exists at boot"), not a one-time token, so trinity-enterprise#49's removal of the setup token stands. POST /api/setup/admin-password now refuses whenever a usable admin exists — its own precondition, fail-closed, checked above the bcrypt hash — instead of trusting the setup_completed flag, which lied on every fresh install. setup_completed is also reconciled at boot on both backends (PostgreSQL had no writer for the key at all).

Before this, --unattended printed a password the operator could not use: the wizard was still forced and replaced it. That is now honest.

Residual, stated so it is not assumed away: the wizard still renders where no admin exists at boot — dev compose with a blank ADMIN_PASSWORD, and a hand-rolled backend. That is exactly the premise ent#49 priced its tokenless window on, so it is the intended state, not a gap in this AC.

Remaining on this issue is the packaging half: registry publish, docker-compose.hosted.yml, cloud-init example, TLS decision, docs.

[obasilakis]

PR #2390 opened — AC1, AC2, AC5, AC6, AC7 (AC3 was already ticked by #2385).

Publish workflow → GHCR, docker-compose.hosted.yml (pull-only, generated from prod, CI-guarded against drift), and start.sh --hosted as a flag rather than a second installer.

Two notes for whoever picks this up next:

• The agent base image is not a compose service and never will be. The backend creates agent containers from the literal local tag trinity-agent-base:latest (hardcoded in lifecycle.py, SEC-172-allowlisted), and compose cannot retag — so --hosted pulls the GHCR copy and tags it locally. A bare docker compose -f docker-compose.hosted.yml up -d therefore starts a platform that cannot create a single agent, failing later at agent-create time. The upgrade instruction is "re-run start.sh --hosted", never "pull". Anything that writes a runbook against the hosted file needs to know this — that includes the feat: DigitalOcean Marketplace 1-Click Droplet listing for Trinity (vendor application + Packer snapshot, AI Agents category) #2281 Packer first-boot script.
• feat: DigitalOcean Marketplace 1-Click Droplet listing for Trinity (vendor application + Packer snapshot, AI Agents category) #2281's Packer first-boot script should write the feat: record install provenance (DO Marketplace) + first-run HTTPS/VPN hardening guide #2380 provenance marker while it is being written anyway (/etc/trinity/install-source or TRINITY_INSTALL_SOURCE=do-marketplace). Adding the line now is free; adding it later means re-cutting and re-submitting the snapshot for Marketplace review.

AC4 is not in this PR — the cloud-init user-data example lives in trinity-ops-public, so it cannot land in a trinity PR. This issue stays open for it (the PR says Refs, not Fixes). That is the last thing between #2280 and done.