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: 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/acme.yml in the repository (a generic host with its gateway: block; every account identifier in it is a placeholder).

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

With provider: aws the engine creates a key pair, a firewall group built from the same firewall lines, one instance and a static address (so the address survives a stop and start), in the account’s default network. It logs in as the image’s own user and becomes root with sudo; the instance’s metadata service answers session tokens only. It uses the credentials your cloud tooling already finds (a role, a profile, the environment), and stores none unless you name them with credentialsFrom. The state bucket, when it is in the same cloud account, must be in the same region.

An existing-host may log in as root or as any user with passwordless sudo.

ingress

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

ingress: direct has the host terminate TLS itself: the proxy listens on 80 and 443, obtains one certificate per hostname from the authority over the HTTP challenge on first use, keeps them in a host directory (so a restart or a recreate keeps them) and redirects 80 to 443. It needs no cloud account and no tunnel. Because the ports are public, you open them with an explicit line (compute.firewall.web: true on a host whose firewall the engine owns; your own firewall on an existing VM), the gateway’s sign-in check does not trust forwarded headers, and the host’s names are plain address records at the host’s own address (written by the DNS provider, or by you under dns.provider: manual: one wildcard record covers them). Certificates are issued per name, so an authority’s rate limits bound how many names one domain can add in a week; point tls.caServer at a staging directory to rehearse.

dns

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

With records: program each developer’s names are kept by a small program of that developer’s own: two developers never wait on each other, a provision never touches the host, and a name that is no longer held is removed by the next run. A host moves to it one developer at a time: on a developer’s next provision or sync, the records written the earlier way under their names are removed and the program creates them. The name is missing for the seconds in between.

With provider: manual the engine writes no record and holds no DNS credential. You create the names yourself, at any DNS host (typically one wildcard record per zone), and each provision or teardown logs which names must resolve to what.

With provider: route53 the host itself keeps one wildcard record per zone, pointing at its own address, in a hosted zone of your cloud account. Every name the engine serves is one label under a zone, so the wildcard covers them all and a provision or a teardown writes nothing. It needs ingress.provider: direct (a wildcard address record can only point at a host that answers on its own address), and the record is removed with the host.

access

The host itself is reached the same way. Under tailscale, every host action (host-up, host-converge, host-diagnostics, fleet-sync, and the container verbs) ssh-es to the host’s tailnet address, never its public one, so the cloud firewall carries no TCP/22 (compute.firewall.ssh is unset and stays unset). On a runner the control-plane workflow installs a pinned tailscale daemon; the engine mints an ephemeral, single-use key under the host’s own tailscale.tag, joins as <host id>-runner-<random> for the length of the job, and logs out at the end (a cancelled job’s node expires on its own). On a machine already on the tailnet, yours included, the engine uses it as is. Two things your tailnet must allow: the OAuth client may mint keys for the tag (auth_keys write, the same it needs for the host), and the tag may reach itself on port 22 (the default policy allows everything; a restrictive one needs tag:X -> tag:X:22). When the tailnet path is not usable the engine says why and tries the public address, which fails by name once the firewall is closed. host-up on a host that is not on the tailnet yet, a new server in particular, applies the firewall twice: 22 open for the one converge that joins it, then closed. FACTORY_TAILSCALE names the CLI prefix (the workflow sets sudo -n tailscale).

secrets

• replicator — the store: the host’s own encrypted store, kept beside its state in a bucket in your own cloud account, with nothing committed to any repository. Needs state.provider: replicator. Seed with replicator secrets set (one name per call, the value on stdin).
• factory-secrets — a JSON name → value map handed to the workflow as ONE secret (FACTORY_SECRETS), for callers that cannot pass many names.

state

The one credential a runner needs is REPLICATOR_STATE_TOKEN: a token scoped to the account that holds the bucket. Pass it as a secret of that name in your repository’s workflow settings.

backend: aws keeps them in a bucket in your cloud account, opened with the credentials your cloud tooling already finds (environment, profile or role); the engine reads and stores none, and no edge account is involved. Scope that role to the state bucket.

backend: local keeps the state and the encrypted secrets in the config folder of the user who runs the verbs ($XDG_CONFIG_HOME, else ~/.config). It needs no account and no token, so replicator secrets set and secrets list work offline. It lives on that one machine: back the folder up, and use the bucket home when a second runner (a workflow, a teammate) must open the same host.

examples/hosts/vendor-free.yml is a complete host that names no vendor: your own VM, ingress: direct, dns: manual, access: ssh-direct and a local state. CI plans it and renders its converge with no vendor credential in the environment.

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.

image.netImage

The image each pod’s net service runs. Unset, it is this distribution’s base image (the baseImage of distribution.json). Set it to a mirror or a fork of that image when your registry is not the default one; it must be the engine’s base image, because the pod’s front door, its network device and its select loop live in it. A private registry also needs image.pull.

gateway

The coordination server — where engineers and their agents sign in, chat, claim repositories, publish heads and hand off work — as a service of the host, and the sign-in every public pod name is behind. It runs only when this block is present; removing the block stops it on the next host-converge and keeps its data volume. A pod with a public port needs it: without it, validate and provision refuse every routed port that does not say auth: none, because nothing would stand between that hostname and anyone who resolves it. The sign-in itself is the web app at app.<zone> (Quickstart, “4. The app”); provision warns when that does not answer.

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

Who may sign in is the admit key above: by default 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 gateway 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 ./clanker.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.

admit is the host owner’s choice and nothing a repository can change. Put admit: all on a host that holds repositories of different teams and a person must have push access to every one of them to sign in. Put a list on a host whose fleet is wider than the people it serves, for example admit: { owners: [platform] } admits whoever can push a repository owned by the platform team (the owner of an entry in the fleet file). The pod’s coordination workspace is still the one pod.default names, even when the list leaves that repository out of the gate.

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/gateway.md.

The web app on the host

By default (app.serve: external) the web app at app.<zone> is published separately (Quickstart, “4. The app”) and the host only sends people to it. With app.serve: host the host serves it itself and nothing else is published:

gateway:
  host: api.acme.example
  imageTag: "<a release that carries the app>"
  app:
    serve: host

• The server image carries the built app. The same service answers app.<zone> on a second port, and the app’s calls to the server never leave that process.
• The host routes app.<zone> to it the way it routes the server’s own name: the same entry points, and a certificate obtained the same way where the host issues its own. The sign-in rules are the app’s own and are the same either way: the session is a cookie no script can read.
• The app’s name must resolve to the host the way gateway.host does. The engine writes no record for it; one wildcard record for the zone covers both.
• imageTag must name a release that carries the app. A converge on an older one fails saying so, and routes nothing.
• No container may claim app.<zone> on such a host, and gateway.host must be a different name.

Switching back to external removes the route on the next converge.

resources (optional)

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

An entry that mixes the two forms is refused.

A provider of your own

The engine ships a few clouds. Any other is a file in your own repository: a module that declares your server (and, if you want, your names) with any infrastructure provider package. The engine runs it inside its own program, keeps its state, shows it in every plan, and does everything after the server exists (logging in, configuring it, the containers, the sign-in) exactly as on every other cloud. Adding a cloud does not mean changing the engine.

# hosts/acme.yml
providers:
  examplecloud: 4.41.0 # the package your module imports, at an exact version

compute:
  provider: custom
  custom:
    module: ../infra/host-provider.ts # relative to this file
    sshUser: root
    env:
      EXAMPLECLOUD_TOKEN: secret:exampleCloudToken # from the host's secret store
    settings: { size: medium, region: north }

// infra/host-provider.ts
import * as cloud from "@pulumi/examplecloud";
import type { HostProvider } from "@clankernet/replicator";

export default {
  compute: {
    declare(ctx) {
      const server = new cloud.Server(ctx.names.server, {
        name: ctx.cloudNames.server,
        size: String(ctx.settings.size),
        sshKeys: [ctx.publicKey],
        userData: ctx.firstBoot,
      });
      return { serverIp: server.ipv4Address };
    },
  },
} satisfies HostProvider;

What your module is given (ctx):

It returns { serverIp }: the address the server answers on. If your cloud gives a server a changing address, attach a static one and return that.

Names. With dns.provider: custom the same kind of module writes the records. hostRecords(ctx, { serverIp }) declares records that live as long as the host, typically one wildcard per zone, which covers every name. With records: per-name, podRecords(ctx, { names, zone, target }) is called with the names one developer holds now, in a small program of that developer’s own: declare one record per name, named ctx.names.extra(name). A name that is no longer passed is removed for you; two developers never wait on each other, and a provision never touches the host.

What stays yours to get right. The module is your code, run with your credentials: the engine does not sandbox it. providers lists every package it imports at an exact version; a package the engine already carries may only be listed at the engine’s own version. A complete module and its spec are in examples/providers/host-provider.ts and examples/hosts/custom.yml; CI runs that pair end to end against a mock cloud.

Refusals

Which secrets a host needs

replicator 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 gateway: is present, each repository’s env.git.tokenFrom, the GitHub App pair (gatewayAppId, gatewayAppPrivateKey, or the names in gateway.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. A host on the aws provider with a wildcard record and ssh-direct access stores nothing but the keypair the first host-up mints: it uses your cloud tooling’s own credentials.

replicator init host writes a spec for one of these shapes and prints exactly the names it still needs (Starting a host).

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.