Getting Started

Install Hatch, run the one-time setup, and map your first domain in under a minute.

1. Install

Hatch is a single binary with no external dependencies. Pick your platform:

macOS (Homebrew)

brew install kingsleyocran/tap/hatch

macOS (binary)

curl -L https://github.com/kingsleyocran/hatch/releases/latest/download/hatch-darwin-arm64 -o hatch
chmod +x hatch && sudo mv hatch /usr/local/bin/

Linux

curl -L https://github.com/kingsleyocran/hatch/releases/latest/download/hatch-linux-amd64 -o hatch
chmod +x hatch && sudo mv hatch /usr/local/bin/

Go Install

go install github.com/kingsleyocran/hatch@latest

2. Setup

Run the one-time setup command. This configures your system DNS resolver so .test domains resolve locally, and installs a trusted certificate authority for HTTPS.

hatch setup

This requires sudo access. Hatch will explain what it's doing before asking for your password.

3. Map a domain

Point a .test domain to any port your dev server is running on:

hatch add myapp.test 3000 --https

Now start your dev server on port 3000 and visit https://myapp.test in your browser. Green lock, real domain, no port numbers.

4. Per-project config (optional)

Create a .hatch.yaml file in your project root to save your domain mappings. When anyone on your team clones the project, hatch scan picks it up automatically.

# .hatch.yaml
domains:
  - domain: myapp.test
    port: 3000
    https: true

What's next

Hatch works out of the box for most projects. Some frameworks need a small config change so their dev server accepts connections through the proxy — especially for HMR (hot module replacement) over WebSocket.

Check the guide for your framework: