Host specs — hosts/<name>.yml

A host spec says where a factory runs: which accounts, which tokens (by name), where the infrastructure state lives. It is owned by the host owner — not necessarily the team whose repository runs on it.

It is non-secret by construction. Every credential is a secret:NAME reference into the secrets store the spec names; no value ever appears in the file. That is what lets a host spec sit in a public repository, travel through a repo: or stack: reference, and be pasted into a support ticket. A literal token anywhere a name is expected is refused.

flowchart TB
  spec["<b>hosts/acme.yml</b><br/>names only — secret:NAME"]
  spec --> compute["<b>compute</b><br/>a server the factory creates,<br/>or a VM you already run"]
  spec --> ingress["<b>ingress + dns</b><br/>a private tunnel to the host<br/>and the public names under your zone"]
  spec --> access["<b>access</b><br/>your private network,<br/>or ssh on the public address"]
  spec --> secrets["<b>secrets + state</b><br/>where names resolve,<br/>where infrastructure state lives"]
  spec --> res["<b>resources</b> (optional)<br/>a bucket, a cache, the coordination server"]

• What you need to own before you can write one: Bring your own cloud.
• Example: examples/hosts/dev-host.yml in the repository (the clankerlabs host, with its clankbase: block).

How a fleet finds a host

host: in the fleet file:

Keys

id, namePrefix

A prefix carries names, never state. Every host is built fresh by host-up; nothing is imported. A state stack that already holds resources the factory did not create is refused before any action runs — the one that holds someone else’s live resources is exactly the one a preview would replace and a host-down would destroy.

compute

ingress

ingress: none is legal (a host reachable over your private network only); a repository with public: ports on it validates with a warning.

dns

Only records carrying managed-by=factory/<id> are ever created, updated or deleted — DNS ownership.

access

secrets

• pulumi-config — the reference deployment: values encrypted into the committed stack file, decrypted by the stack’s own key. On the hosted state service PULUMI_ACCESS_TOKEN is the only credential CI needs; on an s3 backend your passphrase or KMS key decrypts. Seed with factory secrets set.
• pulumi-esc — the state service’s hosted secrets store, referenced from a stack file that holds nothing. Needs state.provider: pulumi-cloud.
• factory-secrets — a JSON name → value map handed to the workflow as ONE secret (FACTORY_SECRETS), for callers that cannot pass many names.

state

State necessarily holds host secrets (the tunnel’s credential, the key resource). The control is who holds the backend and the decryption key (what is in your state).

image.pull.tokenFrom

A registry read token, by name, when the images your host pulls are private. A host that pulls only public images leaves it unset.

clankbase (optional)

The coordination server — where engineers and their agents sign in, claim repositories, publish heads and hand off work — as a service of the host. It runs only when this block is present; removing the block stops it on the next host-converge and keeps its data volume.

Every setting is declared ONCE, in the table packages/engine/src/schema/clankbase-config.ts: its host-spec field, default, whether it is required, and whether it is a credential. The spec fields above, the secret names factory plan asks for, the compose file and the converge’s files are all derived from it.

Who may sign in is not a key of this block: a person is admitted when they can push a repository of the fleet file (any enabled entry of repos[], container or workspace), asked of GitHub with the App — never organisation membership. Every one of those repositories is tracked in the pod’s clankbase workspace, which is named after the pod.default entry (else the first enabled one): its member name, the same as its /workspace/<name> checkout. host up and host converge read the fleet with --fleet (default ./factory.yml) whenever this block is present, offline: only the repository list and pod.default are used, and a fleet with no enabled entry is refused. A host without this block needs no fleet.

The secret values are resolved on your runner and delivered over ssh stdin at each converge as files, never as container environment: each credential is a 0400 file (owned by the container’s user, in a 0700 directory, written under umask 077) that compose mounts under /run/secrets, and the container’s environment only names the file, so docker inspect shows no value. They are never in a container definition, never in the host’s first-boot data, never an output, never a command-line argument. Every line of remote output the engine streams passes a masker holding each resolved secret value first (a value of at least 8 characters, per line). Operating it: docs/operator/clankbase.md.

resources (optional)

Shared backends the host PROVIDES to its pods. A repository consumes one by name and maps its exports to env values (customizations.clankernet.resources); it cannot create one.

An entry that mixes the two forms is refused.

Refusals

Which secrets a host needs

factory plan prints the list with a reason per name, and the workflow checks it before touching a cloud. A host with the hetzner compute provider, a tunnel and private-network access needs hetznerToken, hostSshPrivateKey and hostSshPublicKey (minted by the first host-up), cloudflareApiKey, tailscaleOAuthClientId, tailscaleOAuthClientSecret; plus image.pull, the coordination server’s names when clankbase: is present, each repository’s env.git.tokenFrom, the GitHub App pair (gatewayAppId, gatewayAppPrivateKey, or the names in clankbase.appFrom) when any access.github.org is set, and every name in env.secrets. An existing-host + ssh-direct host needs neither the cloud-provider nor the private-network credentials.

What each host action does

flowchart LR
  up["<b>host-up</b><br/>mint the root key if missing<br/>create server, firewall, tunnel, records<br/>set the host up over ssh"] --> conv["<b>host-converge</b><br/>re-apply the host setup<br/>(proxy, tunnel, private network, coordination server)<br/>safe to re-run"]
  conv --> down["<b>host-down</b><br/>remove the host<br/>refuses while it still provides<br/>a bucket or a created database"]
  down -. only path .-> rd["<b>resources destroy --name</b><br/>empty and delete one backend"]

The host publishes exactly four outputs — serverIp, tunnelId, tailscaleHostname, hostSpec — none secret. The root key lives in the secrets store, the tunnel credential is fetched on your runner, and the private network’s client never leaves it; nothing secret is written into the host’s first-boot data.