16 KiB
Install Hanzo Dev
Hanzo Dev runs coding agents on your computer and lets you control them from its desktop, web, or mobile app. Set up the machine where the agents will work first.
Requirements
You need an installed, authenticated provider before starting a thread. You can launch Hanzo Dev and configure providers afterwards.
Command line
curl -fsSL https://dev.hanzo.ai/install.sh | sh
On Windows, in PowerShell:
irm https://dev.hanzo.ai/install.ps1 | iex
This installs the hanzo command to ~/.local/bin. If that folder is not on your
PATH yet, the installer says so and, for zsh, bash on Linux, and fish, prints
a command to add it. On Windows, hanzo works in the same PowerShell window right
away; add the folder to your PATH for new windows. If a hanzo that the
installer or the desktop app did not create is already there, it leaves that
one alone and stops. Set HANZO_DEV_CHANNEL=nightly to install the nightly train, or
HANZO_DEV_VERSION to pin an exact version.
| Task | Command |
|---|---|
| Start the server and open the web app | hanzo |
| Start the server without a browser | hanzo serve |
| Use it from your other devices | hanzo up (details) |
| Keep it running in the background | hanzo service install (details) |
| Move to the newest release | hanzo update |
| Reclaim database space | hanzo doctor (details) |
| Remove it again | hanzo uninstall |
Run hanzo help or hanzo --help for the full reference. To start in a new working
directory, use an explicit path such as hanzo ./my-project. A bare directory name
is accepted only if it already exists.
If hanzo or hanzo start reports an already running server, run the hanzo pair
command it names and open the pairing URL to connect to that server. Stop it
before starting a replacement, or use a different --base-dir for an
independent server.
To try Hanzo Dev once without installing it, run npx hanzo@latest instead (needs
Node.js for npx). It offers to install the hanzo command first. If you say no,
it asks again at the next minor release, and npx hanzo install installs it later.
npx hanzo always runs the version npm picked, even when a hanzo is installed. On
the nightly train, run your installed hanzo (for example hanzo connect), not
npx hanzo, which runs the latest stable release.
Intel Macs
There is no hanzo executable for Intel Macs (the desktop app is available). To
run a server there, build it from source with vp, which provides the Node version it needs
(Install vp):
git clone https://github.com/hanzoai/dev
cd hanzodev && vp i && vp run build:desktop
node apps/server/dist/bin.mjs
hanzo update and the background service do not apply to a server run this way;
update it with git pull and a rebuild.
Desktop app
Download a release from GitHub Releases, or use a package manager:
| Platform | Install |
|---|---|
| Windows | winget install HanzoDev.HanzoDev |
| Windows (Scoop) | scoop install extras/hanzodev |
| macOS | brew install --cask hanzo-dev |
| Debian, Ubuntu | sudo apt install ./Hanzo-Dev-*.deb |
| Arch Linux | yay -S hanzo-dev-bin |
| Arch Linux nightly | yay -S hanzo-dev-nightly-bin |
| Nix | nix profile add github:NixOS/nixpkgs/nixos-unstable#hanzodev |
Linux
AppImage and .deb downloads are available for x86_64 and ARM64. Check your
architecture with uname -m: for x86_64, choose a file ending in
x86_64.AppImage or amd64.deb; for aarch64, choose arm64.AppImage or
arm64.deb.
To launch an AppImage, open a terminal in its download folder. Replace
Hanzo-Dev.AppImage below with the exact filename you downloaded:
chmod +x ./Hanzo-Dev.AppImage
./Hanzo-Dev.AppImage
The .deb updates itself like the other desktop builds. It asks for your
password to install each update. If your desktop has no password prompt, the
update fails. Download the new .deb and install it the same way.
The AUR packages support x86_64 and ARM64.
Update AUR installs with your AUR helper, such as yay -Syu, instead of the
in-app updater.
Nix (nixpkgs)
Hanzo Dev is maintained in nixpkgs.
The command above installs from nixos-unstable and requires Nix 2.30 or later with
nix-command and flakes enabled. Launch the desktop app with hanzodev-desktop;
the package also includes the hanzo command.
On NixOS, you can instead add the package to your system configuration, using
a nixpkgs revision that includes hanzodev:
environment.systemPackages = [ pkgs.hanzodev ];
Apply the change with sudo nixos-rebuild switch. For Home Manager, add
pkgs.hanzodev to home.packages and run home-manager switch.
Update a profile installation with nix profile upgrade hanzodev. For NixOS or
Home Manager, update your configuration's nixpkgs input or channel and rebuild.
Nix manages both the desktop app and the bundled
hanzo command; use Nix to update them instead of the in-app updater or hanzo update.
The hanzo command
The desktop app includes the hanzo command-line tool. A new install sets it up
on first launch; after an update, or any time, choose Install next to
hanzo command in Settings → About. On macOS and Linux it adds a hanzo link
in ~/.local/bin (or ~/bin); on Windows it adds the app's command folder to
your PATH. Open a new terminal afterwards. If the folder is not on your
PATH, Add to PATH on the Welcome page or in Settings → About adds one
line to your shell's startup file. Remove takes it off, and the app does not
add it again. If you already have another hanzo, it stays as it is.
Windows Subsystem for Linux
Choose a WSL distro in Settings → Sharing & access to run agents and projects there. Install the provider CLIs inside that distro. Hanzo Dev installs its own server runtime there automatically; the first launch after an app update can take longer.
Open a project from a terminal
With the desktop app already running on the same machine:
hanzo app
This opens a new thread for the current directory, adding the project if needed.
Pass a path, such as hanzo app ../my-project, to open another directory. It requires
the desktop app, so a standalone server or an SSH session is not enough. If the
command cannot reach the app, start or update the desktop app and try again.
Drop a folder on the sidebar
Drag one or more folders from Finder, Explorer, or your file manager onto the
sidebar. Each one opens as a project on this computer, the same as hanzo app.
Files dropped on a thread still attach to that thread. Browsers do not share
folder paths, so in the web app use Add project instead.
Mobile app
Install Hanzo Dev from the App Store or Google Play. The phone connects to a server on another machine. Follow remote access to link it through Hanzo Connect or a pairing URL.
Store links and QR codes are also available in Settings → About → Mobile app on web and desktop. The store apps work with both stable and Nightly servers. Test builds are optional:
- iPhone and iPad: TestFlight is invite-only.
- Android: download an APK from the Android beta releases.
If the app crashes during launch, open Settings → Diagnostics on the next launch that succeeds. It lists startup crashes from the last 7 days with the error and component stack that store crash reports leave out. Copy the report and paste it into a GitHub issue. Error messages can quote values from the app, so read it over before sharing.
Providers
Open Settings → Providers in the web or desktop app, select the environment, and enable the provider you want. Installation, login, and configuration belong to that environment's machine, even when you connect from a phone or another computer.
| Provider | Install and authenticate |
|---|---|
| Codex | Connect with ChatGPT, or install Codex CLI and run codex login. |
| Claude | Install Claude Code, then run claude auth login. |
| Cursor | Install Cursor CLI, then run agent login. |
| Grok Build | Install Grok Build CLI, then run grok login. |
| Kiro | Install Kiro CLI, then run kiro-cli login. |
| OpenCode | Install OpenCode, then run opencode auth login. |
| Antigravity | Install and sign in with Google from Hanzo Dev's provider settings. |
| Pi | Install Pi with Node.js 22.19 or newer, then run pi and /login. |
| Muse Code | Install Muse Code on the server, run muse login, then enable it in Settings → Providers. |
| fx | Install fx with curl -fsSL https://fx.sh/setup.sh | bash, then run fx login. |
Provider CLIs must be on the server's PATH. If Hanzo Dev cannot find one, set its
Binary path in provider settings, especially when using a version manager.
Cursor's executable is cursor-agent, although its login command is
agent login. Codex connected through ChatGPT and Antigravity can use their
managed runtimes without a PATH entry.
Hanzo Dev warns when a provider version has known compatibility problems with your release. Check Settings → Providers on that environment for the recommended version or range. When its package manager supports installing a specific version, you can install the recommendation there. Otherwise use the provider's installer on the environment's machine. An unlisted version is unverified.
When a provider CLI is behind its latest release, its provider card shows the
available version. Update now runs the installer that owns the CLI
(Homebrew, mise, or a global npm, pnpm, Yarn, Bun, Volta, or Vite+ install), or
the CLI's own update command when Hanzo Dev cannot tell. Claude, Codex, and
OpenCode installs Hanzo Dev cannot identify stay manual: update them through the
installer you used. Hanzo Dev runs mise upgrade
only for a tool your mise config requests as latest when the provider's binary
path is a mise shim or under the tool's installs/<tool>/latest link; update a
pinned version, or a path into one version's directory, through mise yourself.
Update a CLI installed with Nix through Nix.
Cursor and Antigravity update with Hanzo Dev. Homebrew and Chocolatey installs
compare against the version their package manager offers, which can trail the
npm release; update Claude installed with Chocolatey through Chocolatey.
The managed runtimes for Antigravity and for Codex connected through ChatGPT first install the release Hanzo Dev tested. When Hanzo Dev finds a newer compatible release, their setup in Settings → Providers offers an update.
Add another provider instance for a separate account or configuration. Each instance can have its own environment variables, such as API keys or a custom base URL. Mark secret values as sensitive; after saving, Hanzo Dev does not display their original values.
For provider-specific setup and accounts, see Codex, Claude, OpenCode, Antigravity, Kiro, Pi, Muse Code, and fx.
Provider check timeouts
If a provider works in its CLI but Hanzo Dev reports a timeout while checking it, allow more time in the Hanzo server's environment. For example, give Codex and Claude readiness checks 60 seconds:
HANZO_DEV_CODEX_PROBE_TIMEOUT_MS=60000 HANZO_DEV_CLAUDE_PROBE_TIMEOUT_MS=60000 hanzo serve
For a remote environment, set these on the machine running the Hanzo server.
Keep them in your launcher or service configuration to retain them across
updates, then restart the server. For systemd, add
Environment=HANZO_DEV_CODEX_PROBE_TIMEOUT_MS=60000 under [Service] in a service
override, reload systemd, and restart the service. Provider instances can also
set their own overrides in Settings → Providers.
Each variable extends that provider's readiness-probe deadlines; a phase whose default is already longer keeps its default. Providers with several phases can take longer than one deadline in total. Values must be whole milliseconds no greater than 2147483647; unset or invalid values keep the defaults.
| Provider | Environment variable |
|---|---|
| Codex | HANZO_DEV_CODEX_PROBE_TIMEOUT_MS |
| Claude | HANZO_DEV_CLAUDE_PROBE_TIMEOUT_MS |
| Cursor | HANZO_DEV_CURSOR_PROBE_TIMEOUT_MS |
| Antigravity | HANZO_DEV_ANTIGRAVITY_PROBE_TIMEOUT_MS |
| Grok | HANZO_DEV_GROK_PROBE_TIMEOUT_MS |
| Kiro | HANZO_DEV_KIRO_PROBE_TIMEOUT_MS |
| fx | HANZO_DEV_FX_PROBE_TIMEOUT_MS |
| Pi | HANZO_DEV_PI_PROBE_TIMEOUT_MS |
| Muse Code | HANZO_DEV_MUSE_PROBE_TIMEOUT_MS |
| OpenCode | HANZO_DEV_OPENCODE_PROBE_TIMEOUT_MS |
| ACP Registry agents | HANZO_DEV_ACP_REGISTRY_PROBE_TIMEOUT_MS |
Longer deadlines also take longer to report a stalled check. These overrides cover readiness and discovery, including OpenCode server startup. Usage and config enrichment retain their own shorter limits. Turn execution, package installation, update checks, and shutdown limits keep their existing behavior.
Next steps
- Working with threads: start tasks and organize parallel work.
- Permission modes: choose when agents ask before acting.
- Remote access: connect from another device.
- Running in the background: keep a host available.
- Updating Hanzo Dev: update the app and connected servers.
- Managed policy: configure Hanzo Dev for everyone on a machine.