Read Architecture before changing run coordination, credentials, Sandboxes, publishing, or GitHub authority. Use the extension runbook for agents, Workflows tasks, and GitHub triggers.
Local development requires Render CLI 2.29 or later. It still uses real Render Sandboxes, a real GitHub App, and a real model. Use a test repository and, when possible, a separate App.
Install dependencies and create a local environment file:
npm ci
cp .env.example .envFill .env without committing it. DATABASE_URL can point at a local
Postgres; see Database. Start each process
in its own terminal:
# Terminal 1
npm run dev:workflows
# Terminal 2
RENDER_USE_LOCAL_DEV=true npm run dev:gatewayRENDER_USE_LOCAL_DEV=true directs the Render SDK to start tasks on the local
dev:workflows server instead of the Render API.
Expose port 3000 over public HTTPS:
cloudflared tunnel --url http://localhost:3000
npm run setup:github -- --gateway-url https://<tunnel-host>A GitHub App has one webhook URL. Pointing a production App at local development interrupts production deliveries.
List and invoke local tasks with the Render CLI:
render workflows tasks list --local
render workflows tasks runs start --local \
--task <task> \
--input='[{...}]'Task input schemas are in
app/schemas/tasks.ts.
Run the standard check before handing off:
npm run checkIt runs Biome, TypeScript, and Vitest. Tests fake GitHub, Render, and model
calls. Vitest replaces factory.config.ts with the explicit configuration in
tests/fixtures/config.ts, so customizing your deployment does not change test
subjects, permissions, or expected verification commands. Keep configuration
compatibility cases in that fixture and exercise them through routing and tasks.
Database tests run on PGlite, in-process Postgres, through
tests/helpers/db.ts. PGlite runs one transaction at a time, so tests that
need concurrent transactions or connections run only when TEST_DATABASE_URL
points at a Postgres server where the user can create databases. CI sets it.
Name those files *-postgres.test.ts: Vitest runs them one at a time, since a
transaction anywhere on the server holds back readers of a thread's events.
TEST_DATABASE_URL=postgresql://postgres@localhost:5432/postgres npx vitest run --project postgresRun additional checks when relevant:
shellcheck sandbox/*.sh sandbox/build/*.sh
render blueprints validate render.yaml
npm audit --omit=dev --audit-level=highrender blueprints validate resolves the Blueprint's
env groups in the CLI's current
workspace. Outside a workspace where npm run setup:render has run, expect
only depends on non-existent group errors.
Run one test file with:
npx vitest run tests/gateway.test.tsFollow docs/runbooks/extend.md to:
- add a typed agent and prompt;
- add a GitHub or maintenance task;
- route a GitHub event, label, or command;
- update GitHub App requirements;
- test authority and user-visible behavior; and
- identify required deploys and snapshot refreshes.
The runbook is the canonical procedure. Keep implementation details in code and architectural reasons in Architecture.
README.md: product entry point.docs/quickstart.md: human setup handoff.docs/runbooks/setup.md: first-deployment agent protocol.docs/configuration.md: settings, environment groups, and Day-2 operations (runs, event streams, snapshots, deployment checks, and the database).docs/architecture.md: state, boundaries, invariants, and accepted risks.docs/runbooks/extend.md: extension agent protocol.CONTRIBUTING.md: local development and verification.
Link to the canonical document instead of copying its content.