Declaring Infra
Stand up a central hub to serve all of your repositories:
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:
| Component | Exposure | Role |
|---|---|---|
Router | Public, always on | Receives every connection's events, matches triggers, relays channel replies, mints short-lived code host tokens |
Deployer | Private | Checks and builds outpost containers for the repos the code host allows |
Vault | Private | Holds 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 |
Connection | External platform | Notation Factory's presence on a platform: its credentials, bot identity and event feed. See Connections & Channels |
CodeHost | External platform | Where the repositories live, which of them Notation Factory serves (allow), and the credentials containers push with; an infra has one |
Account | Every outpost that runs its runtime | Credentials for an agent runtime, e.g. CLAUDE_CODE_OAUTH_TOKEN |
OperatorAuth | Your machine | Who 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 state | Default (factory infra up) | With --prune |
|---|---|---|
| Subscribed | Built and routed | Built and routed |
| Unsubscribed or removed | Unrouted; container + /data kept asleep | Container + /data permanently deleted |
Multiple connections
Connect several GitHub organizations, personal accounts or platforms to the same hub:
// …
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 downDestroys 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.