The dev-container file — .devcontainer/devcontainer.json

One per repository, owned by the team that builds in it. It is the standard dev-container file — the same file that opens the repository in any editor that understands the format — and the replicator reads it as-is. The standard fields say what the container is: the image, the ports, the lifecycle commands, the environment. What the standard cannot express lives under customizations.replicator, the standard’s own extension point, so there is one place to write each thing.

flowchart LR
  file["<b>devcontainer.json</b><br/>image · ports · commands · env<br/>+ customizations.replicator"]
  file -- "read at the ref the fleet pins" --> member
  subgraph pod["The engineer's pod"]
    member["<b>A member</b><br/>your image, your clone,<br/>its own ssh port"]
    db[("database")]
    member --- db
  end
  member -- "public ports" --> name["https://web-dev-alice.your.zone"]
  member -- "secrets, by name" --> store["the host's secrets store"]

{
  "image": "ghcr.io/acme/hello:factory", // prebuilt by the repo's own CI
  "forwardPorts": [3000, 5432],
  "portsAttributes": {
    "3000": { "label": "web" },
    "5432": { "label": "db" },
  },
  "onCreateCommand": "git lfs pull",
  "postCreateCommand": { "deps": "npm ci", "seed": "npm run db:seed" },
  "updateContentCommand": "npm ci",
  "containerEnv": { "NODE_ENV": "development" },
  "customizations": {
    "replicator": {
      "$schema": "https://clanker.net/schema/devcontainer-customizations.v1.json",
      "ports": {
        "web": { "public": true, "default": true, "health": "/healthz" },
      },
      "services": {
        "postgres": {
          "databases": ["hello"],
          "exports": { "DATABASE_URL": "hello" },
        },
      },
      "env": {
        "secrets": ["OPENAI_API_KEY"],
        "templated": { "PUBLIC_URL": "https://{hostname}" },
      },
      "lifecycle": { "bestEffort": ["seed"] },
      "procfile": "Procfile",
    },
  },
}

• Schema for the block: https://clanker.net/schema/devcontainer-customizations.v1.json. Set it as the block’s $schema and your editor validates it in place.
• Validate: replicator validate .devcontainer/devcontainer.json --host <id>, or through the fleet file (The fleet file), which reads every listed repository’s file at its pinned ref. Errors name the field in this file’s terms.
• The file is JSONC: comments and trailing commas are fine.
• The file describes the workspace only. A repository’s staging, production, sites and storage live in its environments file.

What happens when

flowchart LR
  clone["clone at the pinned ref"] --> oc["onCreateCommand"] --> pc["postCreateCommand"] --> start["start:<br/>the Procfile, or postStartCommand"]
  sync["every sync:<br/>fast-forward"] --> uc["updateContentCommand"] --> start

A command that fails ends the provision, unless its name is listed in lifecycle.bestEffort. Every command form the standard allows is accepted — a string, an array, or an object of name: command (the names appear in the run summary).

Standard fields, and what the replicator does with them

Refused

The replicator owns the runtime — the storage layout, the network, the routes, the startup — so a field that would bypass it is refused with a one-line reason naming where the thing goes instead:

A top-level field the engine does not know — the standard evolves — is ignored with a warning naming it.

customizations.replicator

Strict: an unknown key is an error. Everything here is what the standard cannot say.

Keys that belong to the standard are refused inside the block, each naming the standard field to use: env.static (→ containerEnv), hooks.postClone / hooks.provision / hooks.sync (→ the three lifecycle commands), features.innerDocker (→ the standard feature), image.ref (→ image), services.procfile (→ procfile), repo.path (→ workspaceFolder), repo.user (→ remoteUser). Two keys belong to the host owner and are refused here because a repository cannot grant itself a host: access (who may hold a container) and host (which host) — both live in the fleet file.

Keeping a process up

Each entry of your procfile runs in its own window, and a port’s label is the name of the window that serves it — that is the whole mapping. The container watches every labelled port whose label is a process it started, and restarts that process when it stops answering. Two things can go wrong, and the second is the one nobody sees:

• The process dies and the port closes. Its window survives, sitting at a finished shell, so simply starting the missing windows again never brings it back.
• The process keeps answering and stops rebuilding. A dev server that builds in a separate child process goes on serving the last thing it built when that child is killed for memory; every edit after that silently does nothing.

The first needs nothing from you. For the second, say what the window builds from and what it writes:

"ports": {
  "sandbox": {
    "public": true,
    "build": {
      "sources": ["workers/sandbox/src/**", "workers/sandbox/wrangler.toml"],
      "output": "workers/sandbox/.wrangler/tmp/dev-*/index.js.map"
    }
  },
  "expo": { "public": true, "watchdog": false }
}

Point output at the source map, not the bundle: a build that produces identical bytes is not written again, so a comment-only edit leaves the bundle file untouched while its map always moves. Sources are compared by content, never by timestamp — the container fast-forwards your checkout on a timer and rewrites the timestamps of files whose bytes did not change.

A check must fail twice in a row before anything restarts, each window then sits out about ten minutes, and every restart is one line in the watchdog window. watchdog: false leaves a window alone entirely — for a process that manages its own lifetime, or one whose port is deliberately not always open.

Who may open a public port

A public port’s hostname is behind the same GitHub sign-in as the app. The host’s ingress asks the coordination server before every request; a browser that has not signed in on that hostname is sent to the app, signs in there (if it has not already), and comes back with a cookie that opens that hostname and no other. The sign-in lasts twelve hours and ends early when the person loses push access to the fleet’s repositories. The container itself sees the request with an X-Forwarded-User header naming the login.

What that gate cannot serve is a caller with no browser: a webhook a provider delivers, a callback a third party posts, a sandbox fetching its inputs. Declare such a port auth: none and its hostname is open:

"ports": {
  "web": { "public": true, "default": true },
  "hooks": { "public": true, "auth": "none" }
}

The port services.s3.public names is none unless it says otherwise: a presigned URL is its own authorisation, and the browsers and sandboxes that carry one hold no cookie. auth on a private port changes nothing — nothing routes it. After provision, a gated default port is probed through the public name like any other, and the gate’s own redirect to the app counts as the route answering; whether the app behind it is alive is checked directly inside the pod.

In a pod

When the fleet that lists this repository has a pod: block (The fleet file), a container of it is one member of the engineer’s pod: it shares one network, one public name and one private-network address with the other members, and runs its own ssh service on its own port. What that changes for this file:

• Hostnames come from the pod. pod.hostnames name every member; the block here is optional and must match if present. The apex (the pod’s one public name) shows this member only while it is the selected one; this member’s own port names ({port}-…) answer whichever member is selected — a public port label belongs to one member of the pod, and what is behind it (a worker, a callback endpoint, a published object store) is not a preview.
• Ports are pod-wide. A port number another member declares, or a member’s ssh port (2201, 2202, …), is refused. So is a second member with services.postgres, services.redis or services.s3: one database, one cache, one object store per pod.
• No container-in-container. The standard docker-in-docker feature is a warning in a pod, and the member runs without it.
• repo.name is the member’s name in the pod, so it must be unique across the fleet’s members and workspaces, must not be net, redis, redis-rest, s3, s3-init, routes or egress, must not be all digits, and must not equal any member’s public port name.
• Siblings are not this file’s business. Every repository of the fleet is a directory of the pod’s shared root: this member’s own checkout at its workspaceFolder AND at /workspace/<repo.name>, every other member’s checkout at /workspace/<its name> (the same files that member runs, read-write), and a clone for each entry without a dev-container file. The fleet decides it (pod.siblings, repos[].pod.sibling); nothing here clones or mounts a sibling repository, and remoteUser must be the same across the pod (it is: developer).

How a connected key reaches a running pod

A key a developer connects from the app (agents.http[].connect) is used by their pod at once, without a provision and without restarting anything:

• The server is wired from the start. Every member holds the pod’s stand-in token for the key, so the MCP server is in every member’s agent configuration even before anything is connected. Until it is, the pod’s proxy answers its requests with a 403 and forwards nothing — closed, never open.
• The pod’s network container watches. It holds the pod’s broker credential (no member does) and waits on the gateway for the developer’s connections to change. When they do, it writes the new key where only the proxy reads it — or the host store’s NAME__<LOGIN> while nothing is connected, or nothing at all — and tells the proxy to reload its files. The members keep running; their open connections are untouched.
• Disconnecting is the same path backwards. The key is removed and the proxy reloaded, so the very next request is refused again; the proxy never keeps serving a key that was taken away.
• A provision does the same thing once, through the same program in the same container, so a provision and the live path always write the same files. If the gateway cannot be asked, that is a warning and the store’s value stands.

Shared library skills in a pod

A pod whose agents.http[] has a connect server also keeps its workspace’s SHARED library skills where the coding agents read them. An owner or admin of the workspace chooses which skills to share; the pod copies those, and only those, into the shared root:

• Where. /workspace/.claude/skills/ce-home--<slug>/, one directory per skill, read by Claude Code in every member. home is the workspace the developer’s key was made in; a key that covers several workspaces syncs that one.
• When. At the end of a member’s boot, and then about once a minute (a library window in the pod.default member, factory-pod-library --watch; the Procfile can declare a library entry of its own). While the key is not connected, or the service refuses it, nothing changes: what is installed stays.
• How. The sync runs as the developer inside a member and asks the service through the pod’s proxy with the same stand-in token the server entry uses, so no member holds the key. Every file is checked against the manifest’s size and SHA-256 before anything is installed; one mismatch refuses that skill and its old copy stays. Files are written read-only, a skill is swapped in as a whole, and a skill that is no longer shared is removed. The limits are 100 items, 20 files of at most 64 KB each per skill, and 2 MB in all.
• What is left alone. A directory without the .clanker-managed marker file is never touched; a symlink is never followed. Agents the workspace shares are listed in /workspace/.claude/library.status and not installed.

factory-pod-library --once runs one pass by hand; library.status holds the state, the counts and the last error (never a credential).

Telling a server which repository an agent is in

An agents.http[] server is written once, for the whole pod, into the shared root’s .mcp.json: a session started at /workspace sends the bearer and nothing else. A server that can pick a workspace by repository (so an agent in one repository’s checkout acts in that repository’s workspace) asks for the repository by naming the header it wants it in:

"http": [
  { "name": "tools", "url": "https://tools.example.com/mcp/", "bearer": "TOOLS_KEY", "repositoryHeader": "x-repository" }
]

For Claude Code, every member then also writes the server into the agent’s own private configuration (~/.claude.json, under each repository’s path) once for every repository of the pod whose URL is GitHub’s: its checkout at /workspace/<name>, and this member’s own checkout at its workspaceFolder. That entry is the same URL and the same Authorization: Bearer ${NAME} plus one header, x-repository: <owner>/<name> — the repository’s GitHub owner and name, lowercased, taken from the pod record and never from a file in a checkout. Claude Code prefers its own configuration over the shared root’s file, and a session anywhere inside a repository’s checkout matches that repository’s path, so the header follows the repository the session started in. Nothing is written into any checkout (nothing to commit or ignore), the credential is still only the ${NAME} reference, the entry exists exactly while the bearer has a value, and a repository that leaves the pod, or a secret that goes, removes it. What the server does with the name is its own business; the header is advisory.

• A session at /workspace itself, a repository whose URL is not GitHub’s, and a server without repositoryHeader send no header.
• Codex does not send it: the server entries written for Codex are user-wide, and a header there would be the same in every directory.
• It is opt-in because the repository name goes to the server. Each member’s file declares it for itself (a member’s agents read its own configuration).

Two files, two owners

The dev-container file says what a container of this repository is. The fleet file — one per host, in the host owner’s repository — says which repositories the host runs, at which ref, and who may hold a pod with each. The host spec says where. A repository never names a host, and a host never edits a repository’s file; at every sync the host re-reads each listed repository’s file at its pinned ref and converges.