Hun

Quick start

Add your first project to Hun, run it and open it in the browser.

In this guide you add a project, run all its services with one click and open it in the browser. The examples use a project called orbit with four services: a web app, an API server, a background worker and Postgres.

Add the project

A project is a folder with a .hun.yml file that lists its services. Hun can write that file for you, or your coding agent can.

  1. In the Hun window, click Add project at the top of the sidebar, or press ⌘N.
  2. Choose the project folder.
  3. Hun reads package.json, Docker Compose files, go.mod and Python project files, and writes a .hun.yml. If the folder already has one, Hun keeps it.
  4. Check the file in Review generated .hun.yml:
    • Accept adds the project to Hun.
    • Open in editor lets you change the file first. Hun checks it as you type.
    • Improve with AI copies a prompt for your coding agent to refine the file.
    • Discard deletes the generated file and adds nothing.

Ask your agent in the project folder:

Set up Hun for this project.

Hun installs a skill for Claude Code, Codex and Cursor that tells the agent how to write .hun.yml, check it with hun validate . and register it with hun add . -y. See Agents.

Run this in the project folder:

hun init

Hun detects your services, asks before writing .hun.yml, then registers the project:

✓ Created .hun.yml
✓ Registered project: orbit

For orbit, the finished file looks like this:

.hun.yml
name: orbit

services:
  app:
    cmd: npm run dev
    port: 3000
  server:
    cmd: uv run server
    port: 8000
    depends_on: [postgres]
  worker:
    cmd: uv run worker
    depends_on: [postgres]
  postgres:
    cmd: docker compose up postgres
    port: 5432

The .hun.yml reference covers every field.

Run it

Select orbit in the sidebar and click Switch in the project header. In Multitask mode the same button says Run. The difference is explained in Focus and Multitask.

Hun starts postgres first, because server and worker depend on it, then the rest. Each service with a port gets it in the PORT environment variable.

From a terminal, the same thing is:

hun switch orbit

Watch it in the menu bar

Click the Hun icon in the menu bar. orbit is listed under Running, with how many services it runs. Hover the row to stop it. Click the row to open it in the Hun window.

Open it in the browser

The :3000 chip on the orbit row opens http://localhost:3000. In the window, click a service's port to open it, or run:

hun open app

Projects under your code folders are found for you

Hun looks for .hun.yml files under ~/side-projects, ~/projects, ~/dev and ~/work, and adds the projects it finds. To scan other folders, set scan_dirs in the global config.

Next

  • Run only part of a project with profiles.
  • Learn what each part of the window does in The Hun window.
  • Let your agent start servers through Hun in Agents.

On this page

Add the projectRun itWatch it in the menu barOpen it in the browserNext