Quick Start
Deploy a Notation Factory hub on Cloudflare, subscribe acme/webapp, trigger Claude Code from a GitHub issue, and resume the session in your terminal. Install the CLI first (see Installation).
1. Deploy the hub (factory.infra.ts)
In your infra repository, add the packages factory.infra.ts imports:
add -d @notation/factory @notation/factory-cloudflare @notation/factory-github @notation/factory-claudeDeclare the hub for the acme organization:
import * as claude from "@notation/factory-claude";
import * as cloudflare from "@notation/factory-cloudflare";
import * as github from "@notation/factory-github";
import { sources } from "@notation/std/resources";
const vault = new cloudflare.Vault("vault");
const router = new cloudflare.Router("router", { vault });
const gh = new github.Connection("gh", { org: "acme", router });
new github.CodeHost("github", { connection: gh, allow: [{ owner: "acme" }] });
new github.OperatorAuth("operators", { connection: gh, users: ["alice"] }); // <-- who may run `factory infra status`
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 }),
});
new cloudflare.Deployer("deployer", {
router,
vault,
accounts: [claudeAccount],
});Sign in to Cloudflare and Claude, then bring the hub up:
wrangler login
export CLOUDFLARE_ACCOUNT_ID="<account id>" # <-- the account that outpost Workers are created in
export CLAUDE_CODE_OAUTH_TOKEN="$(claude setup-token)"
factory infra upfactory infra up deploys the hub, writes its secrets to the vault, and creates the deployer's Cloudflare API token. It opens your browser twice on its first run:
- to create the GitHub App, which it names
<app>--<stage>--gh, with its webhook set to<Url>/webhook/github/gh, whereUrlis the router'sUrloutput; - on Cloudflare, to take the deployer's builds token, a user API token that Workers Builds needs. See Providers.
GitHub returns the App's private key and client secret when it creates the App, and deploy writes them to the vault. See Secrets.
Deploy also prints the router's URL. Name it in factory.config.ts, beside factory.infra.ts, so that factory infra status can reach the hub:
export default {
router: "https://<router's URL>",
};2. Declare an outpost (.factory/)
In acme/webapp, add the packages .factory/infra.ts imports:
add -d @notation/factory @notation/factory-github @notation/factory-claudeWire @claude mentions from collaborators to that container:
import { Container, Trigger } from "@notation/factory";
import * as claude from "@notation/factory-claude";
import * as github from "@notation/factory-github";
const gh = github.Connection.get("gh").channel({ id: "issues" });
const code = new github.Policy("code", {
permissions: { contents: "write", pull_requests: "write" },
});
const dev = new Container("dev", {
runtimes: [claude.runtime], // <-- no image: the default image installs Claude Code from the plugin's setup
policies: [code],
});
const coder = new claude.Agent("coder", { model: "claude-opus-5-5", effort: "high" });
new Trigger("mention", {
event: gh.issueComment({
actions: ["created", "edited"],
mention: "@claude",
from: github.collaborators(),
}),
worktree: (event) => `issue-${event.issue.number}`, // <-- issue #42 -> branch `issue-42`
agent: coder,
container: dev,
});dev has no image, so it runs Factory's default image. To add your own toolchain, see Containers.
Push .factory/ to main so the remote deployer can read it:
git add .factory && git commit -m "Add factory config" && git push3. Subscribe the repository
Name the hub's GitHub App in acme/webapp's .factory/config.ts, by the ID that factory infra up printed when it created the App. The ID is also on the App's settings page. factory repo install finds the App from it:
export default {
githubApps: { gh: 123456 }, // <-- the ID of the App of the hub's connection `gh`
};Grant the hub access to acme/webapp and build its container:
factory repo installfactory repo install walks through installation and waits for the deploy:
1. Opens GitHub in browser ──► Install the GitHub App on `acme/webapp`
2. Webhook wakes Deployer ──► Checks the config, builds `dev`'s image
3. Deploy completes ──► `FACTORY_STATUS` lists `dev` in `builds`, and the check `factory/build dev` shows its build4. Trigger from a GitHub issue
Open issue #42 on acme/webapp and mention @claude:
@claude explain how the request handler validates sessionsThe comment dispatches coder onto issue #42's branch:
Issue #42 comment ──► Router matches Trigger "mention" (author is a collaborator)
──► Deployer calls the worktree function: branch `issue-42`
──► Wakes Container "dev"
──► Checks out `issue-42` in `/data/worktrees/issue-42`
──► Runs Agent "coder" and posts its reply to #42 through the router5. Resume in your terminal
Take over issue #42's session locally:
factory container resume 42Wakes dev and attaches your terminal directly to coder's interactive TUI inside /data/worktrees/issue-42.