The HubDeclaring Infra

Declaring Infra

Stand up a central hub to serve all of your repositories:

factory.infra.ts
import * as claude from "@notation/factory-claude";
import * as cloudflare from "@notation/factory-cloudflare";
import * as github from "@notation/factory-github";
import * as slack from "@notation/factory-slack";
import { sources } from "@notation/std/resources";

const vault = new cloudflare.Vault("vault"); // <-- where the hub's secrets live
const router = new cloudflare.Router("router", { vault });

const gh = new github.Connection("gh", { org: "acme", router });

new github.CodeHost("github", {
  connection: gh,             // <-- GitHub mints narrow tokens through the App
  allow: [{ owner: "acme" }], // <-- only repos owned by "acme" get outposts
});

new slack.Connection("slack", { workspace: "acme", router });

new github.OperatorAuth("operators", { connection: gh, users: ["djgrant", "alice"] });

const claudeToken = new sources.Env("claude-oauth-token", {
  config: { key: "CLAUDE_CODE_OAUTH_TOKEN", track: "scrypt" },
});
const claudeAccount = new claude.Account("claude", {
  auth: vault.secret({ id: "claude-oauth-token", value: claudeToken.credentials.value }), // <-- what outposts' Claude agents run on
});

new cloudflare.Deployer("deployer", {
  router,
  vault,
  accounts: [claudeAccount],
});

Each repository then declares its own outpost in .factory/infra.ts, while factory.infra.ts owns the shared services:

ComponentExposureRole
RouterPublic, always onReceives every connection's events, matches triggers, relays channel replies, mints short-lived code host tokens
DeployerPrivateChecks and builds outpost containers for the repos the code host allows
VaultPrivateHolds the hub's secrets, declared with vault.secret(...). Each connection binds its credentials to the router with router.bind(...), the deployer binds the accounts' secrets, and both bind the root key. See Secrets
ConnectionExternal platformNotation Factory's presence on a platform: its credentials, bot identity and event feed. See Connections & Channels
CodeHostExternal platformWhere the repositories live, which of them Notation Factory serves (allow), and the credentials containers push with; an infra has one
AccountEvery outpost that runs its runtimeCredentials for an agent runtime, e.g. CLAUDE_CODE_OAUTH_TOKEN
OperatorAuthYour machineWho may run the CLI against the running hub. See Operator auth

Each resource carries the package it came from and its version. factory infra up gives the router and deployer the packages they load, and every outpost container the connections', policies' and runtimes', and each installs them from npm when it starts. Upgrading a plugin in the infrastructure repository and running factory infra up redeploys what loads it. A container that lists a runtime no infra Account covers fails its deploy. To add a platform or provider of your own, see Writing Plugins.

Deploying & updating

Reconcile your live cloud resources and subscribed outposts with factory.infra.ts:

factory infra up --dry-run   # preview diff without modifying resources
factory infra up             # apply infra changes and sync subscribed outposts
factory infra up --prune     # delete sleeping containers for unsubscribed repos
Outpost stateDefault (factory infra up)With --prune
SubscribedBuilt and routedBuilt and routed
Unsubscribed or removedUnrouted; container + /data kept asleepContainer + /data permanently deleted

Multiple connections

Connect several GitHub organizations, personal accounts or platforms to the same hub:

factory.infra.ts
// …
const org = new github.Connection("org", { org: "acme", router });

new github.Connection("personal", { router }); // <-- omit `org` for a personal GitHub App

new slack.Connection("slack", { workspace: "acme", router });

All connections deliver events through the shared Router. Only one of them backs the CodeHost; the others are channels only. See Connections & Channels.

Tearing down

Decommission the hub and all of its outposts:

factory infra down --dry-run
factory infra down

Destroys all outpost containers first, then tears down Deployer, Router and the Vault's secrets, and opens browser settings for protected resources (GitHub Apps and Slack apps). A hub re-created later generates a new root key, and needs its connections' credentials set again. See Losing the vault.