Core as a container: process model, config, pairing, state

[qcentic-adm]

Part of #6

Question

How does a Core run as a container rather than as a machine?

Everything about the Core today assumes a real host: actana setup writes a systemd user unit, enables lingering, and the daemon is supervised by systemd. The published "Core image" sidesteps this by running full systemd under --privileged with a hardcoded hostname — which is exactly what we are killing.

Settle:

• PID 1. Does the daemon run directly as PID 1, or under a minimal supervisor? What handles signals and zombie reaping, given the daemon forks PTYs?
• Configuration. On a real machine actana setup is interactive and writes state. In a container, config should arrive as environment variables and a mounted volume. Which env vars, and what is the minimum set to bring up a working Core?
• Pairing. How does a containerised Core get its pairing token and register with the Panel — pre-seeded env var, a token file in the volume, or a first-run flow? What happens on container restart?
• State. What lives in the volume, and what is safe to lose.
• Repos. How does a user's actual work get in — bind mount, named volume, or clone-on-demand inside the container?
• actana setup in a container. Does it still run (in a degraded, no-systemd mode), or does the container image bypass the CLI's lifecycle verbs entirely? These are two quite different designs; pick one.
• The deploy/dev/core.Dockerfile fixture. Does it survive as a local-only test fixture, or is it deleted once the real image can be smoke-tested?

Also decide the shape of the reference docker-compose.yml that runs a Panel and a Core together on one machine — the "people who want both" case.

[qcentic-dev]

Decision — Core as a container

Settled across all eight questions. The shape in one line: the image is the install, tini is PID 1, one env var brings up a Core, one volume is the whole home, and the CLI's lifecycle verbs do not run inside it.

	Decision
actana setup	Bypassed entirely. No unit, no linger, no versions/current, no ActanaServiceManager.
PID 1	tini, baked as ENTRYPOINT. Daemon is PID 2.
Config	ACTANA_PUBLIC_HOST (required), ACTANA_PORT (8443), ACTANA_LABEL. Everything else is a private image constant.
Pairing	First-run mint into the volume. Blob printed once and written to a file; restart reuses.
Host change	Re-issue the server cert from the kept CA. Never re-mint identity.
State	One volume at /home/core — the whole home, agent CLI credentials included.
Repos	The Core takes no position. Bind mount is the demonstrated default; clone-in-shell works too.
deploy/dev/	Deleted, whole tree.
Reference compose	Panel + Core, plain HTTP, no TLS terminator.

---

1. actana setup in a container: bypassed entirely

The image is the install. ENTRYPOINT runs the daemon directly from a fixed path in the image; there is no versioned tree, no current symlink, no unit file, no loginctl enable-linger, and no third ActanaServiceManager implementation.

Every job actana setup does is already done by something else in a container:

actana setup does	In a container
lay out versions/<v> + current	the image tag
write a systemd user unit	ENTRYPOINT
loginctl enable-linger	restart: unless-stopped
systemctl --user enable --now	docker compose up -d
actana update swaps a symlink	docker compose pull && up -d

A degraded no-systemd setup would be a second lifecycle path that nothing supervises, tested forever for the privilege of sharing code with metal. Rejected.

Verb behaviour inside the image. Detected by a baked ACTANA_CONTAINER=1, not by sniffing /.dockerenv.

• Refuse, naming the Docker equivalent: setup, start, stop, restart, update, uninstall.
• Work unchanged: status, token, token regenerate, agents, daemon.

status is worth keeping honest — it is how an operator confirms the endpoint, the protocol version (0.9.0) and agent availability from inside docker compose exec. Its Auto-start row should read the container's restart policy rather than pretending a unit exists.

Metal is untouched. install.sh + actana setup + systemd remains the story for a real machine. This is a second distribution, not a replacement — and the installer e2e (scripts/lib/systemd-container.mjs, which builds its own Dockerfile and purges sudo) keeps covering it.

2. PID 1: tini

ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["actana", "daemon"]

The daemon cannot be PID 1. node-pty forks a shell; the shell forks the agent CLI. When a shell exits while its agent is still running, that agent reparents to PID 1 — and Node's libuv only waitpid()s children it spawned itself. A long-lived Core would accumulate zombies until the PID table fills. Fixing that inside the daemon means native reaping code for one deployment shape.

Baked into the image, not docker run --init / compose init: true — those are opt-in, so anyone copying a bare docker run gets the broken configuration by default. (tini -s is for when tini is not PID 1; as ENTRYPOINT it is, and reaps without the flag.)

Signals already work: harness-entry.ts handles SIGTERM/SIGINT by killing PTYs, closing the WS server, and disposing every store. tini forwards both. A supervisor (s6, supervisord) buys per-service restart for a container with exactly one service — the restart policy belongs to Docker.

3. Configuration

Three documented variables. The minimum for a working Core is one.

Variable	Default	Meaning
ACTANA_PUBLIC_HOST	required	The address the Panel dials. Cert SAN + blob endpoint.
ACTANA_PORT	8443	Listen port; also the blob endpoint's port.
ACTANA_LABEL	the public host	Alias shown in the Panel.

Private image constants, baked as ENV and not part of the contract: AC_CORE_REMOTE=1, AC_CORE_LINK_HOST=0.0.0.0, AC_USER_DATA_DIR, AC_APP_PATH, AC_CORE_MATERIAL_FILE. (AC_HARNESS_* → AC_CORE_* per #12.) Keeping the operator surface separate from the daemon's wiring keeps the README three rows long and leaves the internals free to move.

ACTANA_PUBLIC_HOST is required — the image never guesses. choosePublicHost() picks the first routable IPv4, which is a reasonable guess on metal and a trap in a container: a bare docker run has a container-ID hostname, so a guessing default silently changes the cert SAN on every recreation. Refusing to boot without it is also what retires the hardcoded --public-host core: in the reference compose the value is core, but as a compose fact in a file the operator edits, not an image fact they cannot.

4. Pairing: first-run mint into the volume

On boot the daemon reads material.json from the state volume.

• Missing → mint (CA, server cert, client cert, bearer secret, coreId), persist, write registration-blob.txt beside it, print the blob once to stdout.
• Present → load, start, print nothing.

The operator retrieves it with docker compose logs core or docker compose exec core actana token. Restart is a no-op for pairing. docker compose down -v is the only thing that unpairs.

No secret has to exist before the container does, which is the point — pre-seeding material via env or a mounted secret would need a generator that runs outside a Core, and would put private keys in compose files. Rejected. (This closes the direction cleanly rather than leaving two precedence-ordered paths through identity resolution.)

One code change is required. The daemon's existing fresh-material path (harness-entry.ts, the else branch) mints and prints but does not persist — that was actana setup's job. It must persist when AC_CORE_MATERIAL_FILE is set and the file is absent. persistMaterial() already exists in the same package. The blob should also print human-readably in container mode rather than behind the @@AC_HARNESS_REGISTRATION_BLOB@@ sentinel, and ACTANA_LABEL should feed the label field that path currently hardcodes to "".

5. What happens when ACTANA_PUBLIC_HOST changes

Today resolveMaterial() re-mints everything when the recorded public host differs — new CA, new certs, new coreId, every paired Panel locked out. In a container, a typo'd env var fires that.

Instead: keep the CA key + cert, the bearer secret, the coreId and the Panel's client cert; sign a fresh server cert for the new SAN. The blob the Panel already holds still validates against the same CA; the operator only edits the Core's endpoint if the address genuinely moved. material.json already persists caKey, so this is cheap. It turns "moved the Core" from a re-pair into a non-event.

Note that a full re-mint never actually rescued the moved-Core case anyway — the Panel dials the endpoint stored from the old blob regardless, so re-pairing was required either way. Re-issuing is strictly better: it is reversible and it keeps the Panel's pinned CA valid.

actana token regenerate remains the deliberate way to revoke a leaked blob.

6. State: one volume, the whole home

volumes:
  - core-home:/home/core

What lives there

• ~/.config/actana/material.json — the identity. Lose it and every paired Panel is locked out.
• ~/.config/actana/actana.json — recorded config, incl. the public host the certs were issued for.
• ~/.local/share/actana/data/ — the SQLite: projects, tasks, event log, pins, session icons.
• ~/.claude, ~/.codex, ~/.config/opencode, … — the agent CLIs' own credentials.
• Anything the operator or an agent puts in $HOME, incl. runtime-installed CLIs.

The agent credentials are why the mount is the home and not a narrow /var/lib/actana. Agent CLIs write all over $HOME and enumerating them is a losing game; a narrower mount means every docker compose up logs the operator out of Claude Code. One mount, one backup target.

Safe to lose: registration-blob.txt (re-derivable from material.json), the install tree (owned by the image), logs, PTY scrollback, /tmp, and agent CLIs baked into the image.

One partial state is genuinely broken, and the single volume makes it unreachable. Keeping material.json while losing the SQLite leaves the Panel paired and its per-Core lastEventId cursor ahead of the Core's max event id — the Core replays eventId > afterEventId, returns [], and the Panel goes quiet until the Core's counter catches up. Nothing errors. Anyone hand-restoring one file without the other must reset the Panel's cursor; the volume boundary means normal operation cannot produce it.

7. Repos: the Core takes no position

There is no repo mechanism and none is being added. A Project's path is already just a path on the Core, validated by directory-browse. The container ships git and a persistent home, so:

• Bind mount — what the reference compose demonstrates, because it has been tried and works. The operator's code stays on their own disk, visible to their own editor and their own backups.
• Clone from a VM Shell Session — needs nothing new; git is present and $HOME persists, so credentials survive.
• Named volume — available for anyone who wants the Core to own them.

Making the bind mount actually writable is the real decision here: the daemon runs as a fixed non-root core, uid/gid 1000. 1000 is the first user on essentially every Linux host, so the common case needs no ceremony, and user: "${UID}:${GID}" covers the rest. A named volume at /home/core inherits 1000:1000 from the image on first populate, so actana agents install works without root. Files an agent writes into a bind-mounted repo are owned by the operator — not by root, which is what running as root would inflict on them. A PUID/PGID entrypoint chown was rejected: a root phase at boot plus a recursive chown over a mounted tree, for a case user: already handles.

8. deploy/dev/ is deleted

core.Dockerfile, core-provision.sh, core-provision.service, its docker-compose.yml, and its README.md — all of it. Every file exists to fake a systemd machine so the tarball has somewhere to install, which is exactly the design being killed. The tree is referenced by nothing outside its own README; the installer e2e builds its own fixture inline and is unaffected.

Its only real job — a Panel and a Core on one network — is what the reference compose now does, without --privileged, without /sys/fs/cgroup, without tmpfs: [/run, /run/lock], and without a hardcoded hostname. Keeping it would leave that image in the repo as the thing newcomers copy.

9. Reference docker-compose.yml — Panel + Core

No TLS terminator, and none coming. Operators bring their own nginx / Traefik / existing edge / their own certificates. The Panel already speaks plain HTTP by design (ADR 0010 — "the Panel itself never grows certificate code"), so the reference's job is to name the port to point a proxy at. The current Caddy + Let's Encrypt service is dropped from the reference and becomes, at most, a commented example in DEPLOY.md. This also collapses the public-vs-local file split — there is one file.

This is the browser-facing edge only. The core-link's mTLS is untouched (ADR 0002): the Core presents a self-signed server cert from its own CA and requires the Panel's client cert. That material is minted by the Core, lives in material.json, travels in the registration blob, and is never something an operator supplies or renews. It is the wire protocol, not a deployment choice.

# Panel + Core on one machine. The Panel speaks plain HTTP — put your own
# nginx / Traefik / whatever in front of 127.0.0.1:7420 if you want TLS.
services:
  panel:
    image: ghcr.io/actana/panel:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:7420:7420"
    environment:
      # Optional: hold the secrets key outside the data volume.
      - AC_SECRETS_KEY=${AC_SECRETS_KEY:-}
    volumes:
      - panel-data:/data

  core:
    image: ghcr.io/actana/core:latest
    restart: unless-stopped
    environment:
      # The address the Panel dials. On this network that is the service
      # name — the cert SAN and the blob endpoint both use it.
      - ACTANA_PUBLIC_HOST=core
      - ACTANA_LABEL=${ACTANA_LABEL:-local}
    volumes:
      # Identity, SQLite, and every agent CLI's credentials. Back this up.
      - core-home:/home/core
      # Your repos. Swap for a named volume, or drop it and clone from a
      # shell session instead.
      - ${ACTANA_REPOS:-./repos}:/home/core/repos
    # No ports. The Panel dials wss://core:8443 over this network; nothing
    # on the host reaches the Core.

volumes:
  panel-data:
  core-home:

Pairing, end to end:

docker compose up -d
docker compose logs core          # or: docker compose exec core actana token
# open http://127.0.0.1:7420 → create the Operator → Add Core → paste

Notes on the shape:

• The Core publishes no host ports. Only the Panel reaches it, over the compose network, which is what "only the Panel dials Cores" means here.
• ACTANA_PUBLIC_HOST=core is a compose fact, sitting in a file the operator edits — not baked into the image. A Core on another machine sets its LAN address or DNS name and nothing else changes.
• No privileged, no cgroup: host, no tmpfs, no init:. All four die with systemd, and tini is in the image.
• A second Core is a copy of the service block with a different name, ACTANA_PUBLIC_HOST, and volume. Nothing in the image is singleton.

---

Glossary deltas for the #12 rename sweep

Not applying these here — #12 landed the rename as one sweep of 233 files and #13–#15 execute it. Recorded so CONTEXT.md picks them up:

• Core image — the published container that is a Core: daemon, git, Node, agent CLIs, tini. Distinct from the Core bundle (the tarball install.sh puts on a real machine). Two distributions of the same Core, neither derived from the other. Avoid: container, Docker Core.
• Auto-start unit — the existing entry needs a third case. Its concept ("it comes back on its own") holds in a container; the mechanism is the restart policy, and actana status should say so rather than reporting a unit that does not exist.
• Registration blob — "Reissuing is a machine-side operation" still holds; add that in the Core image, minting is a first-boot operation and the blob is re-readable via actana token for the life of the volume.

Handed on, not settled here

• Core image: pick the base and what ships inside it #8 / base image — this decides nothing about what the Core image is built from, or whether agent CLIs are baked (frame item 2 says they are; the ~1.15 GB / ~1-finding trade-off is Core image: pick the base and what ships inside it #8's).
• Tests: the minimum set that still gives confidence #14 — the daemon changes named in §4 (persist on first mint, label from env, human-readable blob print), the container-mode verb gating in §1, and the cert re-issue path in §5.
• Release: what a tag produces and where install.sh lives #13 — AC_HARNESS_* → AC_CORE_* as part of the sweep.
• Multi-Core-on-one-host works by construction (nothing is singleton) but is not a documented shape yet.

[qcentic-dev]

Closed — outcome recorded on #6. Decisions locked in ADR 0016 D13–D19, D40, D41; the work is #39, #40, #41, #45, #46.

All eight answers carried. Two corrections, both from the cross-check:

• §8's ground for deleting deploy/dev/ is false (C3). It is not referenced by nothing outside its own README — there are eight external references, and one is the release path: container-image.yml:194,203 builds and publishes the core image from deploy/dev/core.Dockerfile. The intent survives entirely; what does not is that deleting it is free. D40 gives the replacement a path — deploy/core.Dockerfile — and One reference deploy/docker-compose.yml; delete deploy/dev/ #45 is explicitly blocked by deploy/core.Dockerfile: Ubuntu 24.04, digest-pinned, toolchain in, Harnesses out #37 so the release path is never broken.
• §7's user: "${UID}:${GID}" is dropped (C7 → D12). It cancels Core image: pick the base and what ships inside it #8's sudo escape hatch for exactly the hosts it exists to serve, and widening sudoers does not save it: NPM_CONFIG_PREFIX still points at an unwritable home, so actana harnesses install fails anyway. The Core is uid 1000, always; non-1000 hosts get chown -R 1000:1000 or a named volume. The rootless-engine caveat (podman unshare chown) is a documentation obligation on docs/install/docker.md.

Two smaller ones: the glossary's "Core image … agent CLIs" and §6's "agent CLIs baked into the image" are corrected — #8 §3 wins and Harnesses are not baked (C5). And §9's dropped Caddy example goes to docs/install/panel.md, not DEPLOY.md, which #15 deletes (C4).

The three glossary deltas you recorded for CONTEXT.md land in docs/architecture/vocabulary.md instead (G2 → #59), since CONTEXT.md is merged away.