software-factory

agent
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Fail
  • exec() — Shell command execution in app/agent-runs/run.ts
  • rm -rf — Recursive force deletion command in app/agent-runs/run.ts
  • process.env — Environment variable access in app/agent-runs/run.ts
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

A template for building coding agent workflows on Render.

README.md

software-factory

Render
MIT License

software-factory is a GitHub-native coding agent template for Render. AI agents
triage issues, write specs, implement them in isolated Render Sandboxes, and
review pull requests. You make the judgment calls.

It's a foundation, not a finished product. The template handles authenticating
GitHub events, running agents in isolated Sandboxes, coordinating overlapping
runs and cancellation, validating agent output, publishing code safely, and
recording every run. You bring the agents, prompts, triggers, approval gates,
and channels your workflow needs.

Deploy to Render

[!IMPORTANT]
Follow the Setup runbook before you apply the
Blueprint. It configures your fork and creates the environment groups the
Blueprint expects. The Blueprint creates a paid Postgres database, and after
applying it you link the database to Workflows
(npm run setup:render -- --link-database) and redeploy factory-workflows.

How it works

  • Triage reads the issue, the discussion, and the repository, then asks
    questions, drafts a spec, or declines. A reply to its questions, or a request
    for changes to its spec, resumes it.
  • Spec-to-PR implements the approved spec, runs your verification
    commands, repairs failures a bounded number of times, and opens a draft pull
    request.
  • PR Reviewer runs your verification commands against a pull request and
    reviews security, correctness, performance, and tests. It posts one COMMENT
    review and never approves or requests changes.
  • Autopilot runs Triage and Spec-to-PR with no approval between them, then
    starts PR Reviewer on the draft pull request.

Each stage is a Render Workflows task that runs its agents in its own Sandbox,
created from a snapshot pre-baked with your repository, its dependencies, and
the agent runner. Agents propose typed results and file trees; code in the
Workflows service checks them and decides every repository, branch, issue, and
pull request the factory touches.

The factory deploys as one Render project:

  • Gateway (factory-gateway, a web service) verifies each GitHub webhook,
    records it, and starts the matching Workflows task. It also serves the live
    event streams. It holds no GitHub credentials and runs no model.
  • Workflows (factory-workflows) runs each task as a durable task run.
    It's the only part that writes to GitHub.
  • Sandboxes run the agents and your verification commands in isolated VMs.
  • Postgres (factory-db) is the source of truth: an append-only event log
    of every delivery, task run, and agent run. It records which run owns each
    issue or pull request, and the status comment on GitHub is rendered from it.

How work arrives

Apply a label to start a stage:

Label Apply to Starts
factory:triage Issue Triage
factory:spec-approved Issue Spec-to-PR, on the issue's current spec
factory:pr-review Pull request PR Reviewer, on the pull request's head commit
factory:autopilot Issue Triage and Spec-to-PR, then PR Reviewer on the draft pull request
  • Labels are commands. The factory removes a label when its run starts, so
    apply it again to run the stage again. It shows factory:working while a run
    is in progress.
  • Replies resume Triage. After Triage asks questions or drafts a spec, a
    comment on the issue resumes it. Comments at other times start nothing.
    Autopilot waits the same way when Triage asks questions.
  • One run at a time. Starting a run on an issue or pull request stops
    whatever was running there.
  • Cancel by commenting /factory cancel on the issue or pull request.
  • Each issue and pull request stands alone. Work runs on the issue or pull
    request it acts on, and its status appears there. Follow, cancel, or rerun
    the review Autopilot starts on its draft pull request like any other.
  • A push to a base branch refreshes that repository's Sandbox snapshot.

Only people with minimumPermission on the repository (write by default)
can start a run.

Security

Credentials stay out of reach of the agents:

  • GitHub write credentials never enter a Sandbox. Clone and fetch credentials
    are read-only and removed before repository code or agents run.
  • Sandboxes reach only an HTTPS allow-list: GitHub and the agents' model APIs.
    Add anything your repository's install and verify commands need.
  • Nothing in a Sandbox holds a database credential. The Workflows host records
    agent runs, and their outcomes and costs come from its own reading of the
    result.
  • Agents load no instructions, skills, or extensions from the repository.
  • Publishing rejects unsafe paths and modes, workflow files, symlinks,
    submodules, oversized changes, and branches with human commits, and GitHub
    must reproduce the candidate tree SHA before the factory publishes it.

Allowed hosts can still carry data out, and the model key exists in runner
memory during a call. Read the trust boundaries
and residual risks before using private
code or untrusted pull requests.

Deploy

Deploy to Render

[!IMPORTANT]
Follow the Setup runbook before you apply the
Blueprint. It configures your fork and creates the environment groups the
Blueprint expects. The Blueprint creates a paid Postgres database, and after
applying it you link the database to Workflows
(npm run setup:render -- --link-database) and redeploy factory-workflows.

The Blueprint creates a software-factory project with
factory-gateway (a Starter web service), factory-workflows (a Workflows
service), and factory-db (a Basic-256mb Postgres database). Sandbox and model
usage are billed separately.

Setup is agent-guided. Prepare a fork of this repository, a Render workspace
with Sandboxes access, a Render API key, an Anthropic API key with a spend
limit, and admin access to each target repository. Then open your fork in a
coding agent:

Set up software-factory by following docs/runbooks/setup.md.
Configure <owner/repository> with base branch <branch>.
Stop at every human checkpoint. Do not print or expose secrets.

The Setup runbook walks the agent through:

  1. Configuring your repositories in factory.config.ts and publishing the fork.
  2. Creating and installing the GitHub App (npm run setup:app).
  3. Creating the Render environment groups from .env (npm run setup:render).
  4. Applying the Blueprint, then linking the database to Workflows
    (npm run setup:render -- --link-database).
  5. Configuring the App's webhook and labels (npm run setup:github) and
    activating the webhook.
  6. Checking both services with npm run doctor, then smoke-testing Triage.

You take over at each checkpoint: committing, creating the App, entering
secrets, approving paid resources, activating the webhook, and labeling the
first issue. See the Quickstart for the full list.

Configure each repository in factory.config.ts:

Setting Required What it does
baseBranch Yes Branch used for Triage, implementation, and snapshots
verify Yes Commands that must pass before publishing, and that PR Reviewer runs
install No Dependency command, run after clone credentials are removed
egress No Extra HTTPS hosts the repository's Sandboxes may reach, or "allow-all"

Labels, minimumPermission, and limits are set in the same file, with their
defaults listed in Configuration.
Agent models are set in app/agents/models.ts, and
secrets and environment groups are covered in Configuration.

Watch agents work

Every agent run is recorded in Postgres with its messages, tool calls, usage,
and cost. The gateway streams them as server-sent events, with the model's
text as it's written. Follow everything on an issue or pull request with the
EVENTS_READ_TOKEN that npm run setup:render saved to .env:

curl -N -H "Authorization: Bearer $EVENTS_READ_TOKEN" \
  https://<gateway-host>/threads/github/<owner>/<repo>/issue/<number>/stream

Use pr for a pull request. A dropped connection resumes where it left off
when the client sends the last event ID it saw as Last-Event-ID. See
Event streams for the per-run endpoint
and the event types.

Local development

Local development uses real Render Sandboxes, a real GitHub App, and a real
model, so use a test repository and, when possible, a separate App:

npm ci
cp .env.example .env
npm run dev:workflows                               # terminal 1
RENDER_USE_LOCAL_DEV=true npm run dev:gateway       # terminal 2

Before you push a change to the factory itself:

npm run check   # lint, typecheck, and tests; GitHub, Render, and models are faked

See Contributing for exposing the gateway to GitHub,
starting tasks directly, and the real-Postgres tests.

Extend the template

The built-in agents and tasks are examples of the template's extension model:

  • Add or replace an agent with a Markdown prompt, a harness (agent library and
    model), a bounded Zod output schema, and the minimum tools it needs.
  • Run agents on another agent library by adding a harness adapter.
  • Define a GitHub task for work attached to an issue or pull request.
  • Add a plain Workflows task for maintenance or other work without an issue
    or pull request.
  • Route new GitHub events, labels, or commands through the authenticated
    gateway.
  • Add a channel beside GitHub, such as Slack or Linear: verify its events in
    the gateway and key its conversations as <channel>:<id> threads in
    app/threads/. The event log, thread ownership, and live streams work for
    any channel; you add its tasks, permission check, and status updates.

The Sandbox runner, run lifecycle, GitHub client, formatting helpers, and
publishing boundary are reusable building blocks. Start with the
extension runbook, which covers the required files,
tests, authority rules, deploys, and snapshot refreshes.

Limits

  • Verification runs shell commands. Browser testing is not included.
  • Turn limits and timeouts bound execution, but the factory has no hard dollar
    budget.
  • Anyone with minimumPermission can start model spend.
  • PR Reviewer runs configured commands against the labeled pull request.

Resources

License

MIT. See LICENSE.

Reviews (0)

No results found