0046 — Foundry agents are lifetime × run type

Persistent agents stay online as a Deployment; ephemeral swarm members are Jobs that must be spun down.

Decided. Agents live in services/foundry. Lifetime is persistent or ephemeral. Run type is on_demand or always_on. The two fields are independent.

A persistent always-on agent stays online as a one-replica Deployment. A persistent on-demand agent has no pod: callers POST /v1/agents/on-demand/{slug} with a Cloudflare JWT and a one-time secret. An ephemeral agent is a temporary swarm Job that the controller must delete on dismiss, stop, or TTL. Do not use a Job for a persistent agent.

always_on accepts scheduled dream and harvest wakes as POSTs to an endpoint. foundry-api has no in-process cron. on_demand only runs when something calls /run or /wake.

foundry-api creates those workloads with its own ServiceAccount. The workloads run in namespace foundry-agents. Harness pods use a second account with no token, a locked-down security context, a NetworkPolicy that allowlists foundry and sibling APIs on port 8080, and a configurable agent node pool. The harness image is Debian 13 (foundry-harness in ACR), not the API distroless image. Start and Stop return the kube error and revert desired_state when the cluster refuses the change. The harness writes a start line and a numbered 30-second heartbeat to stdout and to POST /v1/agents/{id}/logs. Granted tools run on every 15 seconds through broker and runs only the tools the model requests. A skill line names the tool and omits the result. info and warn lines record each evaluate cycle.

Canonical source: docs/decisions/0046-foundry-agents-are-a-lifetime-by-run-type.md.