Hatch

[!IMPORTANT] Hatch is being rebuilt and is not ready for use. The code in this repository is a working prototype of an earlier design that ran every app in Hatch's own AWS account. The new version deploys into your account instead. This README describes what the code does today; the plan is in docs/ and progress is tracked in the roadmap.

Why

Managed platforms like Render and Railway make deploying easy, but your apps run on their infrastructure at their prices. Deploying to AWS yourself keeps you in control, but it takes a lot of setup, and resources left running can quietly turn into a large bill.

Hatch aims to give you the managed-platform experience (connect a repo, push, get a URL, watch logs) on infrastructure you own, with spending limits, idle shutdown, and complete teardown as first-class features. See the vision and cost guardrails.

What works today

The prototype runs the full flow on AWS:

• Sign in with GitHub, browse your repositories, and detect the Dockerfile and exposed port.
• Create a project; with the GitHub App's webhook set up, pushes to its branch redeploy it automatically.
• Build the Dockerfile, push the image to ECR, and run it on ECS Fargate behind a shared Application Load Balancer, with a subdomain per project.
• Stream build and deploy logs to the browser live, and cancel a deployment at any stage.
• Suspend, resume, and delete projects; deletion cleans up the ECS service, target group, task definitions, and images.
• Store environment variables encrypted in Postgres.

Known problems, including the ones the rebuild exists to fix, are listed in Current state.

How the prototype works

Browser ── REST + server-sent events ──▶ API (Go, Gin)
                                 │  GitHub App sign-in, sessions, projects, webhooks
                                 │
                                 ▼  job "build" (River, in Postgres)
                               Build job
                                 │  git clone → docker build → push to ECR
                                 │
                                 ▼  job "deploy"
                               Deploy job
                                    task definition → target group →
                                    host-based ALB rule → ECS service →
                                    wait until healthy

Logs:  build / deploy jobs → Postgres (deployment_logs, NOTIFY) → API log stream (SSE) → browser
Data:  PostgreSQL (sqlc queries on pgx, jobs on River, migrations embedded in the binary)

Deleting, suspending, and resuming a project are jobs too (destroy_app, scale). Each job is queued in the same database transaction as the change that causes it. hatch serve runs the API and the job runner together; hatch worker runs only the job runner.

Where it is going

The rebuild replaces this with one Go program and Postgres. You connect your AWS account by launching a CloudFormation stack that creates a limited role, and Hatch builds with CodeBuild and runs your apps on ECS Fargate in that account. A local Docker target comes first, so the whole flow can be developed and tested without AWS. Details are in the architecture and the decision records.

Running locally

You need Go 1.27 (an older Go downloads it automatically), Node.js 24 (set by engines in web/package.json), pnpm (it switches itself to the version pinned in web/package.json), Docker, and a GitHub App for sign-in; setting one up takes a few minutes.

git clone https://github.com/YHQZ1/Hatch.git && cd Hatch
(cd web && pnpm install)

# Configuration: fill in the GitHub App values and DATA_ENCRYPTION_KEY. Every hatch command reads this one file.
cp .env.example .env

make infra     # Postgres in Docker
make migrate   # apply database migrations (hatch migrate)
make dev       # run hatch serve and the Vite dev server

Open http://localhost:3000. The Vite dev server there forwards /api, sign-in, and live-log requests to hatch serve on port 8080. make stop-dev stops everything make dev started.

To run the single binary instead, make build builds the web UI into bin/hatch, and bin/hatch serve then serves the UI and the API together on port 8080.

By default Hatch uses the local target (HATCH_TARGET=local): it clones a repository, builds its Dockerfile with this machine's Docker, runs the image as a container, and serves it at http://<name>.localhost:8081 through a reverse proxy built into hatch serve. It needs Docker running and no AWS account. Deploying a repository still needs the GitHub App installed on it, because the build clones with the App's installation token.

HATCH_TARGET=aws keeps the old hosted path, which needs an AWS account with an ECR repository, an ECS cluster, and an ALB, set in .env.

Repository layout

cmd/hatch          the hatch binary: `serve`, `worker`, and `migrate` commands
internal/api       REST API, GitHub OAuth and webhooks, the log stream (SSE)
internal/build     cloning, building, and pushing images (Docker, ECR)
internal/runtime   running apps: local Docker containers, or ECS services and ALB routing
internal/proxy     the built-in reverse proxy for <name>.localhost
internal/jobs      the background jobs (build, deploy, delete, pause and resume)
internal/store     database access (sqlc) and migrations
internal/config    configuration loading
internal/secrets   encryption at rest
web/               React + Vite dashboard, embedded in the binary
docs/              vision, architecture, roadmap, and decision records

Where this layout is heading, and why, is in ADR 0008.

Documentation

Document	Contents
Vision	What Hatch is for and who it serves
Current state	What the prototype does and its known problems
Architecture	The target design
Cost guardrails	How Hatch keeps cloud spend under control
Roadmap	Phases, checklists, and current status
Open questions	Decisions still to make, and decided ones

Security

Please report security issues privately as described in SECURITY.md, not in public issues.

License

MIT