Configuration

The .hun.yml file is the brain of your project. Ideally, you commit this to git so your team shares the same environment.

The Basics

A minimal config looks like this:

name: my-project

services:
  web:
    cmd: npm run dev
    port: 3000

Service Definition

Each key under services is a unique service name.

cmd (Required)

The command to run.

cmd: python manage.py runserver

cwd (Optional)

Directory to run the command in, relative to project root.

cwd: ./backend

port (Optional)

The port this service listens on. hun needs to know this to manage port collisions in Multitask Mode. If omitted, hun assumes the service doesn't bind a port (like a worker). When present, hun always publishes the selected launch port as PORT. The configured value is used when available; a Multitask fallback such as 3001 is published when the base port is occupied. This is the preferred base port. In Focus mode it is strict: hun rejects the launch if that TCP port is occupied. In Multitask mode hun uses it unchanged when free and searches upward by ports.default_offset only when this service's port is occupied. A per-port lease prevents concurrent hun services or instances from selecting the same port while an application is still starting. Runtime detection verifies listening sockets against the launched process group before updating the live port shown in the UI. Focus mode rejects a different verified listener; Multitask mode adopts it safely.

port: 8080

port_env (Optional)

If your app reads the port from a custom environment variable, tell hun which one. hun always injects the selected port as PORT and also injects it into this custom variable. That is normally the configured port, or the first available fallback for this service in Multitask mode. The selected value takes priority over inherited environment variables and values under the service's env section. This field is an optional alias, not a separate source of truth.

port_env: API_PORT  # hun sets both PORT and API_PORT to 8000 (or its fallback)

env (Optional)

Environment variables specific to this service.

env:
  NODE_ENV: development
  DATABASE_URL: postgres://localhost:5432/db

ready (Optional)

A string to look for in the logs to know when the service is "Ready". Until this string appears, hun status will show the service as STARTING.

ready: "Listening on port 3000"

Global Hooks

You can define scripts to run before starting or after stopping the project.

hooks:
  pre_start: ./scripts/ensure-db-running.sh
  post_stop: ./scripts/cleanup-temp-files.sh

Log Configuration

Control how logs are handled for this project.

logs:
  max_size: 10MB   # Rotate after 10MB
  max_files: 5     # Keep 5 rotated files
  retention: 7d    # Delete logs older than 7 days

Example: Full Stack App

Here is a common setup for a modern web app.

name: social-network

services:
  # Frontend (Next.js)
  web:
    cmd: npm run dev
    cwd: ./web
    port: 3000
    ready: "Ready in"

  # Backend (Go)
  api:
    cmd: go run main.go
    cwd: ./api
    port: 8080
    port_env: A_PORT
    env:
      DB_HOST: localhost
    ready: "Server starting on :8080"

  # Database (Docker)
  db:
    cmd: docker compose up postgres
    ready: "database system is ready to accept connections"