This runbook separates source validation, account mutation, deployment, and live verification. Commands are dry-run/read-only unless marked mutating. Never paste secrets into command history.
- Configure
factory_config.pyfor eachOWNER/REPOSITORY. - Run
uv sync --locked,uv run preflight, andmake check. - Run
render blueprints validate render.yaml. This does not deploy. - Confirm
factory/workflows/app.pyexists and registers the expected tasks before deploying. If it is absent, the current implementation milestone is not deployable.
Create a Blueprint from the fork's render.yaml. Review the proposed resources before applying:
- web service
factory-gateway, Python,starter - Workflow
factory-workflows, Python, with no service-level plan - environment groups
factory-gatewayandfactory-workflows - no database
The Workflow inherits the repository containing the Blueprint. If Render validation asks for an explicit repo
URL, use the fork URL in the Dashboard rather than committing a canonical repository URL that would break forks.
Wait for the gateway URL before creating the GitHub App. A Blueprint apply/deploy is an external mutation and is intentionally not performed by any setup script.
Generate a manifest and local POST form:
uv run setup-app \
--gateway-url https://YOUR-GATEWAY.onrender.com \
--output tmp/github-app-manifest.json \
--html-output tmp/create-github-app.htmlFor organization ownership, add --organization ORGANIZATION. Inspect the JSON, open the HTML locally, and submit
it to GitHub. The redirect lands on the gateway root with a one-time code in the address bar. Exchange it within
one hour:
uv run setup-app --exchange-code CODE --credentials-output tmp/github-app.envThis exchange is mutating and consumes the one-time code. The output file is mode 0600 and contains the App ID, private key, and webhook secret. Transfer values to Render, then securely delete the file.
Install the App on only the configured repositories. The manifest subscribes to issues, issue_comment,
pull_request, and push, with contents/write, issues/write, members/read, metadata/read, and pull-requests/write.
Run the read-only/dry-run handoff:
RENDER_API_KEY=... RENDER_WORKSPACE_ID=... uv run setup-renderCreate the sandbox group explicitly:
RENDER_API_KEY=... RENDER_WORKSPACE_ID=... uv run setup-render --apply-groupPut the resulting sbg-... ID in FACTORY_SANDBOX_GROUP_ID on factory-workflows. Populate both environment
groups exactly as described in configuration.md. Never add RENDER_ADMIN_API_KEY to a
service.
Credential brokering is optional. The default brokered_model_access=False keeps every model loop in Workflow
compute while tools remain sandboxed. To enable in-sandbox loops, configure the restricted credential with:
RENDER_ADMIN_API_KEY=... ANTHROPIC_API_KEY=... \
uv run setup-render --group-id sbg-... --apply-credentialRun the live broker probe, then set brokered_model_access=True and redeploy. If credential administration is
unavailable, keep the safe default; never copy ANTHROPIC_API_KEY into a sandbox.
First validate App access without writes:
uv run setup-github OWNER/REPOSITORY --checkThen explicitly create/update labels (mutating):
uv run setup-github OWNER/REPOSITORY --apply-labelsRepeat for every repository in factory_config.py.
Deploy from a committed, pushed revision. Environment-group changes need a deploy before the running service sees them. Then run:
uv run doctor --remote \
--gateway-url https://YOUR-GATEWAY.onrender.com \
--repository OWNER/REPOSITORY \
--env-file .envAlso verify in Render that all expected Workflow tasks registered. To perform the broker probe in a disposable
sandbox, rerun the command with --probe-brokering. This creates a sandbox and makes one minimal billable model
request, so use it only in an authorized workspace. The implementation sends no provider key in input, files,
commands, or environment.
Finally send a GitHub ping, inspect Recent Deliveries, and trigger Triage on a disposable issue. Success requires
the expected GitHub result, not merely HTTP 202 or a queued task.