Skip to main content
Hatch is configured entirely through environment variables. This page documents all available configuration options.

​
Database

​
DATABASE_URL
string
required
PostgreSQL connection string in the format postgres://user:password@host:port/database?sslmode=disableDefault: postgres://hatch:hatch@localhost:5432/hatch?sslmode=disableExample: postgres://hatch:[email protected]:5432/hatch?sslmode=disable

​
HTTP API

​
HATCH_HTTP_ADDR
string
Address and port for the Hatch REST API serverDefault: :8080Example: 127.0.0.1:8080
​
HATCH_BETTER_AUTH_VERIFY_URL
string
Better Auth API key verification endpoint used by hatchd middleware for authenticationDefault: http://127.0.0.1:3000/api/auth/api-key/verifyExample: http://127.0.0.1:3000/api/auth/api-key/verify
​
HATCH_BASE_DOMAIN
string
required
Base domain for the Hatch deployment. Used for VM subdomain routing.Example: hatchvm.com
This must match your DNS configuration and Traefik certificate resolver setup.

​
Reverse Proxy

​
HATCH_PROXY_ADDR
string
Address and port for the reverse proxy that routes traffic to VMsDefault: :9090Example: 127.0.0.1:9090
​
HATCH_PROXY_BASE_DOMAIN
string
Domain suffix for VM subdomain routing. When a request comes to my-agent.hatchvm.com, it routes to the corresponding VM.Default: hatch.localExample: ${HATCH_BASE_DOMAIN} or hatchvm.com
​
HATCH_PROXY_WAKE_TIMEOUT
duration
Maximum time to wait for a paused VM to wake up when receiving a proxy requestDefault: 60sExample: 30s, 2m

​
Data Storage

​
HATCH_DATA_DIR
string
Directory for storing VM-related data, snapshots, and runtime filesDefault: ./dataExample: /data or /var/lib/hatch

​
S3 Snapshot Storage

Hatch uses S3-compatible storage for VM snapshots. MinIO is recommended for local deployments.
​
HATCH_S3_ENDPOINT
string
S3-compatible endpoint URL for snapshot storageExample: http://127.0.0.1:9000
Required for snapshot functionality. Leave empty to disable S3 snapshots.
​
HATCH_S3_BUCKET
string
S3 bucket name for storing VM snapshotsExample: hatch-snapshots
The bucket must exist before starting Hatch. S3 functionality is enabled only when this is set.
​
HATCH_S3_REGION
string
S3 region for the bucketDefault: us-east-1Example: us-east-1 (for MinIO, this can be any value)
​
HATCH_S3_ACCESS_KEY
string
S3 access key ID for authenticationExample: minioadmin
Keep this credential secure. Do not commit to version control.
​
HATCH_S3_SECRET_KEY
string
S3 secret access key for authenticationExample: minioadmin
Keep this credential secure. Do not commit to version control.

​
Firecracker Configuration

​
HATCH_FIRECRACKER_BIN
string
Path to the Firecracker binary executableDefault: firecrackerExample: /root/firecracker/firecracker
​
HATCH_DEFAULT_KERNEL_PATH
string
Path to the default Linux kernel image for VMsExample: /root/firecracker/vmlinux-5.10
When both HATCH_DEFAULT_KERNEL_PATH and HATCH_DEFAULT_ROOTFS_PATH are set, Hatch auto-seeds a default image with ID img_default.
​
HATCH_DEFAULT_ROOTFS_PATH
string
Path to the default root filesystem image for VMsExample: /root/firecracker/ubuntu-noble-rootfs.ext4
Must be an ext4 filesystem image compatible with your kernel.
​
HATCH_DEFAULT_VCPU
integer
Default number of virtual CPUs for new VMsDefault: 1Example: 2
​
HATCH_DEFAULT_MEM_MIB
integer
Default memory allocation in MiB for new VMsDefault: 512Example: 1024
​
HATCH_DEFAULT_BOOT_ARGS
string
Default kernel boot arguments for VMsDefault: console=ttyS0 reboot=k panic=1 pci=off root=/dev/vda rw rootfstype=ext4

​
Networking

​
HATCH_BRIDGE_NAME
string
Name of the network bridge interface for VM networkingDefault: fcbr0
​
HATCH_BRIDGE_CIDR
string
CIDR notation for the bridge networkDefault: 172.16.0.1/24Example: 10.0.0.1/24
​
HATCH_SSH_ALLOWED_CIDR
string
CIDR range allowed to access SSH forwarding portsDefault: 127.0.0.1/32 (localhost only)Example: 0.0.0.0/0 (allow all - not recommended for production)
Restricting SSH access is critical for security. Only allow trusted networks.
​
HATCH_SSH_PORT_MIN
integer
Minimum port number for SSH forwarding port rangeDefault: 16000
​
HATCH_SSH_PORT_MAX
integer
Maximum port number for SSH forwarding port rangeDefault: 26000
This range allows up to 10,000 concurrent VMs with SSH forwarding.

​
Idle Management

Hatch automatically pauses VMs that have been idle to save resources.
​
HATCH_IDLE_TIMEOUT
duration
Duration of inactivity before a VM is considered idle and automatically pausedDefault: 45mExample: 30m, 1h, 2h30m
Set to 0 to disable automatic pausing. Adjust based on your usage patterns and resource constraints.
​
HATCH_IDLE_CHECK_INTERVAL
duration
How often the idle monitor checks for inactive VMsDefault: 5mExample: 15m, 10m
Lower intervals provide faster response but use more CPU. Recommended to be at least 5-10 minutes.

​
Better Auth (Web Application)

These variables configure the web application’s authentication system.
​
BETTER_AUTH_URL
string
Base URL for the Better Auth web applicationDefault: http://localhost:3000Example: http://localhost:3000
​
BETTER_AUTH_SECRET
string
required
Secret key for Better Auth session encryptionExample: replace-with-32-plus-char-secret
Must be at least 32 characters. Generate a secure random string for production.
​
GOOGLE_CLIENT_ID
string
Google OAuth client ID for authenticationExample: replace-with-google-client-id
Required only if using Google OAuth for authentication.
​
GOOGLE_CLIENT_SECRET
string
Google OAuth client secretExample: replace-with-google-client-secret
Keep this credential secure. Do not commit to version control.

​
Docker Compose Variables

These variables are used by the Docker Compose setup for infrastructure services.
​
CF_DNS_API_TOKEN
string
Cloudflare API token for DNS challenge in Let’s Encrypt certificate generation
Required for wildcard SSL certificates. See Deployment for setup details.
​
ACME_EMAIL
string
Email address for Let’s Encrypt certificate notificationsExample: [email protected]
​
POSTGRES_USER
string
PostgreSQL database userDefault: hatch
​
POSTGRES_PASSWORD
string
PostgreSQL database passwordDefault: hatch
Change the default password in production.
​
POSTGRES_DB
string
PostgreSQL database nameDefault: hatch
​
MINIO_ROOT_USER
string
MinIO root usernameDefault: minioadmin
Change the default credentials in production.
​
MINIO_ROOT_PASSWORD
string
MinIO root passwordDefault: minioadmin
Change the default credentials in production.

​
Example Configuration

Here’s a complete example .env file for a production deployment: 
# Database
DATABASE_URL=postgres://hatch:[email protected]:5432/hatch?sslmode=disable

# Domain
HATCH_BASE_DOMAIN=hatchvm.com

# HTTP API
HATCH_HTTP_ADDR=127.0.0.1:8080
HATCH_BETTER_AUTH_VERIFY_URL=http://127.0.0.1:3000/api/auth/api-key/verify

# Reverse Proxy
HATCH_PROXY_ADDR=127.0.0.1:9090
HATCH_PROXY_BASE_DOMAIN=hatchvm.com

# Storage
HATCH_DATA_DIR=/data
HATCH_S3_ENDPOINT=http://127.0.0.1:9000
HATCH_S3_BUCKET=hatch-snapshots
HATCH_S3_REGION=us-east-1
HATCH_S3_ACCESS_KEY=SECURE_ACCESS_KEY
HATCH_S3_SECRET_KEY=SECURE_SECRET_KEY

# Firecracker
HATCH_FIRECRACKER_BIN=/root/firecracker/firecracker
HATCH_DEFAULT_KERNEL_PATH=/root/firecracker/vmlinux-5.10
HATCH_DEFAULT_ROOTFS_PATH=/root/firecracker/ubuntu-noble-rootfs.ext4

# Network Security
HATCH_SSH_ALLOWED_CIDR=10.0.0.0/8

# Idle Management
HATCH_IDLE_TIMEOUT=45m
HATCH_IDLE_CHECK_INTERVAL=15m

# Better Auth
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=GENERATE_A_SECURE_32_PLUS_CHARACTER_SECRET_HERE
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Docker Compose
CF_DNS_API_TOKEN=your-cloudflare-token
ACME_EMAIL=[email protected]
POSTGRES_PASSWORD=SECURE_PASSWORD
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=SECURE_PASSWORD
Replace all default passwords and secrets with secure, randomly generated values before deploying to production.

Build docs developers (and LLMs) love

Get started for freeTalk to us