Software Factory

Why deploy software-factory on Render?

software-factory is an extensible starting point for coding agents that work inside GitHub. Its included workflow triages an issue, turns an approved specification into code, runs your repository's checks, opens a draft pull request, and posts a review. People control every transition with GitHub labels and comments, and the factory never approves or merges code.

The template goes beyond the agent loop. It handles the operational problems around one: signed webhooks, durable execution, overlapping runs, cancellation, idempotency, isolated repository access, typed agent output, and safe publishing. Render Workflows owns long-running execution and retries. A short-lived Render Sandbox holds the checkout, the agent, and every command the agent runs.

Fork the template and list the repositories it may access. You can run the included issue-to-PR workflow as is, replace one agent at a time, or reuse its runner, claim lifecycle, GitHub client, and publishing boundary for a different GitHub automation.

Architecture

The public gateway verifies each GitHub webhook signature and maps the delivery to one Workflows task. It holds no GitHub credential and runs no model or repository code.

The Workflows service runs every task. It restores a Sandbox from a prepared repository snapshot, runs the agent inside it, validates what comes back, and performs every GitHub write. GitHub stays the system of record for issues, specifications, labels, pull requests, reviews, and the visible claim on each piece of work. Render Workflows records each task's status, timing, input, result, and retries. There is no application database or separate queue.

What you can build

After setup, apply factory:triage to an issue. The factory reads the issue and the repository, then asks up to five focused questions, declines the request, or posts a bounded specification as a comment. A maintainer reviews the specification and applies factory:spec-approved. The factory implements that exact specification, runs your verification commands, repairs failures a bounded number of times, and opens a draft pull request. Apply factory:pr-review to any pull request to run the same checks and post a non-approving review covering security, correctness, performance, and tests.

For trusted work, factory:autopilot grants upfront approval for all three stages. Each stage still runs as its own child task with its own compute, status, and Sandbox. Autopilot stops when Triage needs an answer and continues after a person replies.

While a task runs, the issue or pull request shows a factory:working label and an App-authored status comment with progress, the run ID, and the final outcome. There is no web UI: you use the factory entirely through GitHub.

Key features

• Human-gated issue-to-PR workflow: Triage, specification approval, implementation, and review are controlled with GitHub labels and comments. Autopilot is opt-in, and the workflow ends at a draft pull request and a comment-only review.
• Durable execution on Render Workflows: Every stage has a recorded input, result, status, and retry boundary. GitHub delivery IDs become Workflows idempotency keys, so redelivered webhooks don't start duplicate runs.
• Short-lived, isolated Sandboxes: The agent loop and every model-directed tool run beside the checkout in a Sandbox, never on the credentialed Workflows host. Agents and repository commands run as an unprivileged user.
• Prepared repository snapshots: A push to the base branch rebuilds a dependency-installed snapshot. Each run still fetches and verifies the exact commit it was asked to work on.
• Typed agent contracts: Every agent is a prompt, a model, a minimal tool set, a strict output schema, and a turn limit. The built-in agents use Claude Sonnet 5 for Triage and PR Reviewer and Claude Opus 5 for writing specifications and code, and changing one is a one-line edit. Results are validated in the Sandbox and again by trusted host code.
• Constrained publishing: GitHub write credentials never enter the Sandbox. Host code rejects unsafe paths, workflow files, symlinks, submodules, oversized changes, and branches with human commits, and publishes only after GitHub reproduces the candidate tree's SHA.
• Claiming and cancellation without a database: The App-authored status comment names the active run and its Sandbox. A replacement run or a /factory cancel comment stops the old run and terminates its recorded Sandbox.
• Repository-level configuration: factory.config.ts defines the allowed repositories, base branches, install and verification commands, trigger labels, minimum GitHub permission, and publishing limits. Agent models live in app/agents/models.ts.

Use cases

• A platform team turns approved feature requests into tested draft pull requests while keeping final review and merge human-owned.
• A maintainer adds consistent first-pass triage and specification writing across several repositories.
• An engineering organization builds a repository-aware migration, maintenance, or dependency-update agent on the same isolation and publishing boundaries.
• A developer studies a production-style pattern for running coding agents without placing GitHub write credentials in the agent's environment.

What's included

The Blueprint creates both services in a software-factory project in Oregon. Sandboxes are temporary resources created for snapshot builds and task runs.

The repository also includes four workflow paths (Triage, Spec-to-PR, PR Reviewer, and Autopilot), setup scripts that create the GitHub App, environment groups, webhook, and labels, a read-only doctor diagnostic for each service, structured JSON telemetry, tests that pin the security and coordination invariants, and runbooks for first-time setup and extension.

Prerequisites

• A fork of the repository. factory.config.ts in your fork defines the exact GitHub repositories the factory may access.
• A Render workspace with Sandboxes access in Oregon.
• A Render API key.
• A dedicated Anthropic API key with a provider-enforced spending limit. The key enters the Sandbox during agent runs, and the factory has no hard dollar budget.
• Admin access to each target GitHub repository so you can create and install the factory's GitHub App.
• Paid Render resources. The Blueprint creates a Starter web service and a Workflows service. Sandbox and model usage are billed separately.
• Node.js, using the version in the repository's .node-version, for setup and diagnostics.

Next steps

Setup is agent-guided. The factory needs your repository allowlist committed and its secrets stored in environment groups before the Blueprint is applied, so a coding agent walks you through it and stops wherever you need to act.

1. Fork the repository. Deploy from your fork, not the upstream repository.

2. Open your fork in a coding agent and ask it to follow the setup runbook:

3. Complete the human checkpoints. The agent configures factory.config.ts, creates the GitHub App, creates the Render environment groups from your local .env, and connects the webhook. It pauses for you to approve the commit and push, create and install the App, enter your Render and Anthropic keys, apply the Blueprint, activate the webhook, and create the smoke-test issue. You never paste a secret into chat or the Blueprint form.

4. Verify the deployment. Both services should be live, and npm run doctor should pass for the gateway (in its Render Shell) and for Workflows (locally, with the deployed values).

5. Run the Triage smoke test. Apply factory:triage to a test issue. The App should add a status comment and end with questions, a specification, or a decline.

6. Run the full pipeline. Try a small request step by step, or apply factory:autopilot to a new issue to go from issue to draft pull request and review in one run.

7. Extend the factory. Change prompts, schemas, or models, add an agent or a GitHub task, or add a plain Workflows task using the extension runbook.

Security notes

Issue text, comments, source files, dependency scripts, and pull request diffs are untrusted. The template keeps authority in code rather than prompts: authenticated task input selects every repository, ref, branch, and write target; only the Workflows host writes to GitHub; and the Sandbox returns only a typed result or a candidate file tree. Clone credentials are read-only, temporary, and removed before any repository code or agent runs.

Sandboxes use allow-all egress, and the model key exists in runner memory during a model call. The runner removes provider keys from tool environments and runs as a non-dumpable process, but those controls do not make arbitrary untrusted code safe. Anyone with the configured minimum permission can start model spend, and PR Reviewer runs the labeled pull request's commands. Read the architecture guide's trust boundaries and residual risks before using private code or untrusted pull requests.

Current limits

• Verification runs shell commands. Browser testing is not included.
• Turn limits and timeouts bound each run, but there is no hard dollar budget.
• Sandbox API calls count against the Render workspace's request limit.
• There is no web UI. You use the factory through GitHub labels and comments.

Resources

• software-factory README
• Quickstart
• Setup runbook
• Configuration reference
• Architecture and trust boundaries
• Extension runbook
• Render Workflows docs
• Render Sandboxes docs