Hatchery

Hatchery is a software factory. It coordinates coding agents in Vercel Sandboxes to monitor, investigate, modify code, open pull requests, and send notifications.

Work is organized into agents, which share repositories, reference material, and Git-backed memory across chats and scheduled jobs. Hatchery can be used from its web UI or through Slack and GitHub.

How to use

Get onto the instance's allowlist (HATCHERY_ALLOWED_EMAILS)
Open the instance's URL

Note that everybody from the allowlist can view and participate in everybody else's chats through any channel. Use your own judgement when choosing what kind of work to do there.

How it works

Agents are shared and named, like hatchery (the default one, created on first use). Each has an ID (also its Git folder and web address), a display name, repos, and settings in the database.
Git storage. Each agent's files live in the storage repo under agents/<id>/: AGENTS.md (who the agent is), USER.md, MEMORY.md, memories/, skills, scripts, api/ routes, and schedules/ jobs. wiki/ holds the team prompt (wiki/PROMPT.md) and team skills; it appears on main with the first reviewed wiki change. Creating an agent commits a starter folder. No secrets go into Git.
Threads. A chat is a thread. It gets its own branch and sandbox before its first model call, loads its files from the branch, works with shell and file tools, and saves its changes back. Ordinary changes merge to main on their own; wiki and serving changes wait for review. A thread can hand work to child threads. Each agent has a daily token budget. Long histories are compacted. fx subagents and extra sandboxes work as before.
Serving. Python handlers in api/<route>/route.py on main answer at https://<agent>.<HATCHERY_SERVE_DOMAIN>/<route>, in one sandbox per agent. A reviewed change goes live without a Hatchery deploy.
Secrets are encrypted in the database, belong to one agent, and only reach that agent's serving sandbox. Agents can ask for a secret; people set, rotate, reveal, and delete them on the agent's API page.
Schedules. schedules/<name>/job.py runs on a cron or an interval, and people can pause it. Prompt jobs (a saved prompt on a cron) also work as before.

See docs/arch/ for details and docs/agentmesh-migration.md for the design.

Upgrading from 0.1 keeps the old data and queue topics. Nothing is dropped. Chats, Slack/GitHub links, prompt jobs, and sandbox records start fresh in new tables. Old chats and notes don't show up. See docs/arch/store.md.

Configuration

Set these on the Vercel project. Production and Preview are set separately; see docs/deployments.md for what Preview has.

Variable	What it does
`DATABASE_URL`, `DATABASE_URL_UNPOOLED`	Postgres: pooled for the app, direct for Rotor's LISTEN/NOTIFY. Production and Preview need separate databases.
`VERCEL_APP_CLIENT_ID`, `VERCEL_APP_CLIENT_SECRET`	The Sign in with Vercel app.
`HATCHERY_ALLOWED_EMAILS`	Comma-separated emails that may sign in. Missing or empty denies everyone.
`HATCHERY_APP_ORIGIN`	Production only: the public origin used for sign-in redirects and origin checks. Previews use their own URL.
`CRON_SECRET`	Production only: Vercel sends it to the minute heartbeat at `/api/cron`.
`ROTOR_RELEASE_SECRET`	Bearer token for `POST /api/rotor/activate`, which forces a deployment to take Rotor over.
`HATCHERY_STORAGE_REPO`	Storage repo for agent files, as `<owner>/<repo>`. Without it, agents have no Git files.
`GITHUB_CONNECTOR`	The Connect GitHub app (`github/hatchery`). Its installation needs read and write access (contents, pull requests) to the storage repo. `HATCHERY_GITHUB_INSTALLATION_ID` picks an installation; `GITHUB_TOKEN` is a fallback.
`GITHUB_APP_SLUG`	The GitHub app's slug, used by the GitHub channel.
`SLACK_CONNECTOR`	The Connect Slack app (`slack/hatchery`).
`HATCHERY_SERVE_DOMAIN`	Domain for agent web addresses. The project also needs the wildcard domain `*.<HATCHERY_SERVE_DOMAIN>` (a project setting, not `vercel.json`).
`HATCHERY_SECRETS_KEY`	32-byte key (base64url) that encrypts agent secrets. Keep it stable: a new key can't read old secrets.
`BRAINTRUST_API_KEY`, `BRAINTRUST_PARENT`	Traces go to Braintrust when both are set.
`VERCEL_TOKEN`, `VERCEL_TEAM_ID`	Sandbox auth fallback when Vercel OIDC isn't available.
`HATCHERY_<SECTION>_<FIELD>`	Optional limits, defaulting to agentmesh's values: `MODEL` (`ID`, `MAX_OUTPUT_TOKENS`, `CONTEXT_WINDOW_TOKENS`), `THREAD` (`MAX_TURNS`, `BASH_CALLS_PER_TURN`, `COMMAND_TIMEOUT_SECONDS`, `SANDBOX_IDLE_SECONDS`, `COMPACT_ABOVE_TOKENS`, `KEEP_RECENT_MESSAGES`, `MAX_DELEGATION_DEPTH`, `MAX_DELEGATIONS_PER_THREAD`), `BUDGET` (`TOKENS_PER_DAY`), `REVIEW` (`WORKSPACE`, `SERVE`, `WIKI`: `auto` or `review`), `SERVE` (`REVISION_TTL_SECONDS`, `REQUEST_TIMEOUT_SECONDS`, `JOB_TIMEOUT_SECONDS`, `MAX_REQUEST_BYTES`). See `backend/hatchery/config.py`.

Development

Hatchery is developed and tested only through Vercel preview deployments. Locally you run the tests (make ci), not the app.

This repo builds the vercel-hatchery package. It does not deploy the app: an instance deploys from a wrapper repo that pins the package. Never run vercel deploy from this repo. See docs/deployments.md for previews, production releases, and what previews can't do.

Use docs/use-agent-browser.md for browser-driven testing and docs/use-braintrust.md to inspect agent runs.

The frontend is a Vite React SPA using TanStack Router and is served by FastAPI. The backend uses Rotor and the AI SDK for Python. Hatchery runs Rotor workers on Vercel Queues, uses Vercel Sandboxes for coding agents, Lakebase Postgres on Neon for storage, and Vercel Connect for Slack and GitHub integrations.

Python distribution

The PyPI distribution is vercel-hatchery (imported as hatchery). Run make build or make ci from the repository root. Publishing uses GitHub Actions trusted publishing; see backend/README.md for the one-time setup and release steps.