factory.yml — the manifest

factory.yml says what to run. It lives in the caller repo, at the root, and it is the only file named factory.yml anywhere in the system (plan D9). The where — accounts, tokens by name, state — is the host spec it points at through host.ref.

Everything a developer container needs is declared here and generated from here: the compose environment: block, the Traefik routes, the env file, the tmux windows. Nothing is read out of the container image at provision time, so the image can be generic (factory-base) and the repo-specific part is this file.

• Schema: schema/factory.schema.json (generated from packages/engine/src/schema/factory.ts; put # yaml-language-server: $schema=… at the top for editor completion). The JSON Schema is deliberately looser than factory validate: refinements such as “exactly one default port” or “{port:NAME} names a public port” cannot be expressed in JSON Schema, so always run the CLI.
• Full example: examples/factory.clankerengineer.yml.
• Minimal example: examples/factory.minimal-node.yml.
• Validate: node packages/engine/bin/factory.js validate <path> from a CLANKERNET checkout (the reusable workflow’s preflight runs the same verb, plan T050). NOT npx factory — the package is private and unpublished, and factory on the public registry is an unrelated module. Exit 0 = valid; warnings go to stderr and do not fail the run.

Placeholders

One grammar for every templated string (hostnames, env.templated, coordination.actorLabel, access.tailscale.hostname). Unknown placeholders are validation errors, not literal text in an env var.

Keys

version (required)

1. The manifest format version.

repo (required)

host (required)

host.ref — where the host spec is. Three forms:

The workflow’s host input (plan T050) overrides the manifest’s ref, so a repo can be provisioned onto a different host without editing the file. It — and --host on every CLI verb, validate included — also takes a host id (hosts/<id>.yml in the CLANKERNET checkout, FACTORY_ROOT) or a path to a .yml in the caller’s checkout, beside the three ref forms above.

image (required)

access

Refused: access.github with neither org nor users — an empty block would authorise everyone the repo’s workflow_dispatch already does, while looking like a restriction.

hostnames (required)

Templates must end in .{zone}. Cloudflare’s free Universal SSL covers exactly one label under the zone (*.example.com), so {user}.{repo}.{zone} is refused unless advancedCertificate: true — an Advanced Certificate is a paid, per-zone order, and the failure without one is a 526 on first visit.

The compose project name is derived from default: dev-{user} when the template is exactly dev-{user}.{zone} (the legacy clankerengineer shape, so provision reconciles a running container instead of recreating it), else {user}-{repo}.

ports (required, ≥1)

Refused: two defaults, a path-routed default, duplicate names or numbers, health on a non-default port, pathPrefixes on a non-path-routed port.

services

Omit postgres for no database. There is deliberately no shared cloud database seam: one shared project meant one container’s schema push was visible in all of them.

resources

Host-stack resources the container gets credentials for. Both kinds are { protect: true } on the host stack; nothing in the default program deletes them, and factory resources destroy --host H --name N is the only path that empties and deletes one (plan D4).

env

The container’s env file is the union of five disjoint sets, and the validator refuses a name declared twice or a name the engine reserves.

Reserved (set by the engine, refused here): FACTORY_USER, FACTORY_REPO, FACTORY_HOSTNAME, FACTORY_ZONE, GITHUB_USERNAME, SSHID_USERNAME, TAILSCALE_AUTH_KEY, GIT_TOKEN, GIT_USER_NAME, GIT_USER_EMAIL, REPO_URL, GITFWD_HOME, GITFWD_REPO.

hooks

Each list holds commands (a plain string, fatal) or { run, name?, fatal? }. Hooks run in repo.path as repo.user with the env file sourced. fatal defaults to true: a silently half-provisioned container is exactly the bug the legacy entrypoint’s || true produced.

agents

features

coordination

Present = the container joins a GFP/1 coordination space; absent = no GitFWD at all (env | grep -c GITFWD is 0).

sync

teardown

Refusals and warnings, in one place