Deploying
What happens when you run hatch deploy, how to control it, and how to debug it.
The deploy flow
Run it from your project (or build output) directory:
hatch deployThe CLI packs your directory into a tar.gz artifact (honoring .hatchignore; .git/ and .env* are always excluded), uploads it, and the platform builds and starts your egg. You get a live URL within seconds. If no egg exists yet, one is created — optionally named with --name myapp.
Which egg gets deployed is resolved from .hatch.toml in the directory (written on first deploy). Commit it to keep deploys pinned to the same egg.
Runtimes and flags
Hatch auto-detects your framework; override when needed:
hatch deploy --runtime node --deploy-target dist --start-command "node server.js"--runtime — one of node, python, go, rust, php, bun, static
--deploy-target — directory to upload (your build output)
--start-command — how to start the app (required for non-static runtimes)
--name — egg name on first deploy · --domain — attach a custom domain
Static sites (--runtime static) are always free, never consume energy, and require a .hatchignore when deploying from a source directory.
Go/Rust binaries must be built for linux/amd64 — e.g. CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build. The CLI checks the binary architecture before uploading and tells you the exact cross-compile command if it doesn't match.
Redeploys, history and rollback
Every subsequent hatch deploy replaces the running version atomically. The dashboard's app page shows the deployment timeline (status, commit) and lets you roll back to a previous successful deployment in one click.
Remember the filesystem is ephemeral across deploys: /app is reset every time. Keep state in the PostgreSQL addon or an external store.
Troubleshooting
hatch logs --build # build output
hatch logs -f # live runtime logs• Build fails — check hatch logs --build; most failures are a missing --start-command or deploying source instead of build output.
• App won't start — it must listen on the PORT env var and bind 0.0.0.0.
• exec format error — your binary isn't linux/amd64; cross-compile as above.
New here? Start with Getting Started, or let your AI agent do it — see the agent instructions page.
