Hun is a Mac app that runs your project's dev servers, workers and databases from a .hun.yml file in the project. It starts them in dependency order on free ports, keeps their logs, and shows what's running from your menu bar. The hun command and your coding agents control the same services, so everything ends up in one place.
Install
Download the app, paste your license key and get the hun command.
Quick start
Add your first project and run it.
Menu bar
See what's running, and run, stop or switch projects.
The Hun window
Services, logs, branches and a terminal for each project.
Agents
Let Claude Code, Codex or Cursor start servers through Hun.
.hun.yml reference
Every field, with its type, default and behaviour.
CLI reference
Every hun command, with flags and sample output.
Troubleshooting
Fixes for ports, Docker, the license and stuck services.
How Hun works
Hun has three parts:
- The app. A menu bar item and a main window. It shows your projects and their services, and sends your clicks to the daemon.
- The daemon. A background process that starts and stops your services, picks their ports and keeps their logs. Closing the window doesn't stop anything; the daemon keeps your services running.
- The
hunCLI. The app comes with it and puts it on your PATH. Every command talks to the same daemon, and starts it if it isn't running.
The daemon keeps its files in ~/.hun:
| Path | What it holds |
|---|---|
~/.hun/daemon.sock | The socket the app and the CLI use to talk to the daemon |
~/.hun/state.json | Registered projects, what's running and each project's last profile |
~/.hun/logs/ | Service logs, one file per service |
~/.hun/config.yml | Optional global settings, see global config |
If the daemon restarts, it starts the projects that were running before.