Installation

Run ACPDash locally, then install it as a background service if you need it available between terminal sessions.

Requirements

Install these on the machine that will run the host:

Requirement	Notes
Bun	Use the version pinned in the root `package.json`, currently 1.3.14, or the 1.4.0 version documented in the repository README.
Git	Each project uses a local Git repository. Commit an initial revision before selecting its branch.
SQLite 3.51+	The host requires a compatible SQLite shared library.
Agent provider	Install and authenticate a supported provider before starting an agent.
GitHub CLI	Install and authenticate `gh` if you need GitHub pull request checks.

Use the Bun installation guide to install Bun. On Apple Silicon macOS, install SQLite with Homebrew:

brew install sqlite

The host automatically checks /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib. For another installation, set ACPDASH_SQLITE_LIB to the absolute shared-library path. Installing a newer sqlite3 command alone does not guarantee that Bun loads that library.

Start the local host

Clone the repository and run these commands from its root:

git clone https://github.com/pmdroid/acpdash.git
cd acpdash
bun install --frozen-lockfile
bun start

Open http://127.0.0.1:4317 in your browser. bun start builds the web client and runs the host in the foreground. Stop it with Ctrl-C.

The dashboard can start without provider credentials. Before sending a task, make sure your chosen provider works under the same operating-system account as the host.

Run a separate instance

If the default ports are already in use, give the second instance its own ports, database, and worktree directory:

PORT=4340 ACPDASH_PREVIEW_PORT=4341 \
  ACPDASH_DATA=data/dev/acpdash.sqlite \
  ACPDASH_WORKTREES="$PWD/data/dev/worktrees" \
  bun start

Open http://127.0.0.1:4340. Do not point two hosts at the same database or worktree directory.

Install a background service

The service installers require Tailscale installed, signed in, and available on PATH. They build the web client, configure the user service, and set up Tailscale Serve. Use the URL printed by the installer.

For macOS with launchd:

bun run install:macos

For Linux with a systemd user service:

bun run install:linux

Service settings live in ~/.config/acpdash/environment. Use one unquoted NAME=value per line. The installer stores Web Push keys there, so keep the file private. Foreground bun start does not automatically load it.

Service data lives in ~/.local/share/acpdash/. Keep the checkout in its installed location because the service executes the source from that directory.

Installed preflight guide

Both service installers package the acpdash-preflight skill pointer and the canonical closeout instructions:

Platform	Installed directory
macOS	`~/Library/Application Support/acpdash/skills/acpdash-preflight`
Linux	`~/.local/share/acpdash/skills/acpdash-preflight`

Each package contains SKILL.md, agents/openai.yaml, the extracted instructions.md, and a version file. Agents can also retrieve the same text through the host’s get_closeout_instructions tool, including when running the host in the foreground.

Read preflight and retries for the workflow and optional command failure limit.

Update an installation

Back up the service data directory and configuration before updating. Stop the host before copying the database, or use SQLite’s backup facilities for a consistent backup.

After updating the checkout and installing its locked dependencies, reinstall the macOS service. This also refreshes the packaged preflight guide:

bun install --frozen-lockfile
bun run install:macos

For an existing Linux service, rebuild the client, refresh the packaged guide, and restart the host:

bun install --frozen-lockfile
bun run build
bun scripts/package-preflight.ts \
  --dest "$HOME/.local/share/acpdash/skills/acpdash-preflight"
systemctl --user restart acpdash.service

Continue with the quickstart. If the host does not start, see troubleshooting.