Configuration
Configure the host with environment variables and keep each instance's ports and storage separate.
Host settings
These are the primary settings used by the host. Foreground runs inherit the shell environment. Installed services use their generated configuration.
| Variable | Default | Purpose |
|---|---|---|
HOST |
127.0.0.1 |
Dashboard bind address. |
PORT |
4317 |
Dashboard HTTP port. |
ACPDASH_DATA |
data/acpdash.sqlite |
SQLite database path, relative to the process working directory unless absolute. |
ACPDASH_WORKTREES |
Sibling <repository-name>-agents directory |
Root for agent worktrees. |
ACPDASH_SQLITE_LIB |
Automatic Apple Silicon Homebrew lookup | Optional SQLite shared-library path. |
ACPDASH_PUBLIC_ORIGIN |
Unset for foreground runs | Client-facing dashboard origin used by host origin checks and links. |
Preview settings
| Variable | Default | Purpose |
|---|---|---|
ACPDASH_PREVIEW_BIND |
HOST, or 127.0.0.1 |
Preview server bind address. |
ACPDASH_PREVIEW_PORT |
4318 |
Separate preview listener. |
ACPDASH_PREVIEW_ORIGIN |
Derived local origin | Client-reachable preview origin for remote access. |
Use a different hostname for previews and the dashboard. Do not treat a port change as hostname isolation. For remote setup, see remote and mobile access.
Storage locations
| Data | Foreground default | Installed service |
|---|---|---|
| Database | data/acpdash.sqlite |
~/.local/share/acpdash/acpdash.sqlite |
| Proof and uploads | data/content/ |
~/.local/share/acpdash/content/ |
| Worktrees | Beside each project repository | ~/.local/share/acpdash/worktrees/ |
| Service environment | Not automatically loaded | ~/.config/acpdash/environment |
Notification and terminal state also live under the service data directory. Back up the whole directory and the environment file. Stop the host before copying SQLite files, or use a consistent SQLite backup.
Service environment
Use unquoted assignments, one per line:
PORT=4317
ACPDASH_PREVIEW_PORT=4318
ACPDASH_PREVIEW_BIND=127.0.0.1The installer records its environment and generates Web Push keys. Preserve those keys during an update. The provider executable overrides are listed in agent providers.
After changing settings, restart the service. On macOS, rerun bun run install:macos to regenerate the launchd configuration. On Linux, restart acpdash.service with systemctl --user.
Repository closeout settings
Closeout requirements belong in the repository’s .acpdash/closeout.yaml, rather than the host environment. The version 1 policy can require recorded commands, receipts, Cucumber or visual proof, independent review, CI, and resolved review threads.
Set retry.maxFailedAttemptsPerItem to an integer from 1 to 20 to limit failed executions of each pinned command item. Omit retry for no host attempt limit. The host pins this configuration from the base commit for each issue revision; changing a worker’s copy does not update its active requirements.
See preflight and retries for a complete YAML example and the recovery flow.
Development commands
bun run check
bun run test
bun run build
bun src/host/server.tsbun run dev starts Vite alone. It does not start or proxy the host API. Use the host URL for the complete application, rebuild after frontend changes, and restart after host changes.