Band Band

Installation

Band is distributed as a macOS desktop application. The app bundles both the dashboard UI and the web server that manages your projects, workspaces, and chat panes.

System requirements

  • macOS 11 (Big Sur) or later
  • Apple Silicon (M1 and later) or Intel Mac — both architectures are shipped as separate signed builds
  • Git installed and available on your PATH
  • A coding agent CLI such as claude, codex, or opencode installed and configured

Download

Download the latest .dmg file from the GitHub Releases page. Each release ships per-architecture artifacts:

  • Band-<version>-arm64.dmg for Apple Silicon Macs (M1 and later)
  • Band-<version>.dmg for Intel Macs

The matching .zip archives are used by the in-app auto-updater (electron-updater) — you don't need to download them manually.

Install the app

  1. Open the downloaded .dmg file.
  2. Drag Band.app into your Applications folder.
  3. Eject the disk image.
  4. Open Band from your Applications folder or Spotlight.

Releases are signed with an Apple Developer ID and notarized via notarytool, so Gatekeeper should not show a "damaged" or "from an unidentified developer" warning on first launch. Local builds compiled from source are unsigned — see CONTRIBUTING.md for how to handle those.

First launch

When Band starts for the first time, it does the following:

  1. Creates the ~/.band directory to store configuration and state (band.db, settings.json, logs).
  2. Generates a token in ~/.band/settings.json for authenticated access from the CLI and remote tunnel.
  3. Starts the web server on port 3456 (configurable via the webServerPort setting).
  4. Detects installed coding agents (claude, codex, opencode) and seeds the codingAgents setting with the ones it finds.
  5. Installs Claude Code hooks (PreToolUse, PermissionRequest, UserPromptSubmit, PostToolUse, Stop) so agent status is reported back to Band.
  6. Prompts to install the band CLI symlink at /usr/local/bin/band (requires admin password).
  7. Opens the dashboard window.

The web server runs in the background as long as Band is open. You can also access the dashboard from any browser at http://localhost:3456 (you'll be prompted for the token from ~/.band/settings.json the first time).

The Band CLI

Band includes a command-line interface that lets you manage projects, workspaces, chat panes, terminals, browser tabs, and cronjobs from your terminal. The CLI binary is bundled with the desktop app and communicates with the web server over HTTP.

After installing Band, you can verify the CLI is working by running: 

band projects list

If band is not on your PATH, open Settings → About in the dashboard and click Install CLI — that creates the /usr/local/bin/band symlink with admin privileges.

Verify the server is running

You can confirm the web server is up by visiting http://localhost:3456 in your browser. To poll the health endpoint from a script, include the token from ~/.band/settings.json: 

TOKEN=$(jq -r .tokenSecret ~/.band/settings.json)
curl "http://localhost:3456/api/health?token=$TOKEN"
# {"status":"ok","app":"band-web-server","hostname":"…"}

Next step

Now that Band is installed, head to Adding your first project to register a git repository.