Getting StartedIntroduction

Introduction

Notation Factory runs coding agents in remote containers and connects them to the places your team talks:

  • Listens to messages on your communication channels (GitHub issues, Slack, etc.)
  • Dispatches agents into remote outposts (Cloudflare Containers, Railway, E2B, etc.)
  • Connects you directly to remote agents over a secure line (SSH, Tailscale, etc.)

The Hub

Stand up a central Notation Factory hub for your organisation to serve all of your outposts.

factory.infra.ts
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" }] });

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] });

The Connection (in this case, a GitHub App) is Notation Factory's presence on a platform. It sends events to the Router, which holds its credentials.

The CodeHost decides which repos Notation Factory serves, and mints the short-lived credentials containers use to push code.

The Deployer provisions agent containers when a new outpost comes online (e.g. the GitHub App is installed on your repo), and gives them the Account credentials their agents run on.

The Vault holds the hub's secrets. vault.secret(...) only declares a secret. The router and the deployer each bind the secrets they use, and nothing else reads them. Each connection binds its credentials to the router, and the deployer binds the accounts' secrets.

Outposts

Triggers

Wake an agent when someone you trust mentions it on an issue:

.factory/infra.ts
const gh = github.Connection.get("gh").channel({ id: "issues" }); // <-- this repo's issues

const dev = new Container("dev", {
  image: "./Dockerfile",
  runtimes: [claude.runtime],
  policies: [code],
});

const coder = new claude.Agent("coder", { model: "claude-opus-5-5" });

new Trigger("mention", {
  event: gh.issueComment({ mention: "@claude", from: github.collaborators() }),
  worktree: (event) => `issue-${event.issue.number}`, // <-- issue #42 works on branch `issue-42`
  agent: coder,
  container: dev,
});

A Trigger is the whole dispatch rule: this event, from these authors, to this agent, in this container, on the branch worktree names. Commenting @claude on issue #42 runs coder on branch issue-42 and posts its reply back to the issue. See Declaring Outposts.

Terminal handoff

Take over a running issue session from your local terminal:

factory container resume 42

Opens an SSH connection to dev and attaches your local terminal directly to issue #42's branch and Claude session. See Conversations & Sessions.