Architecture

A local Bun host coordinates providers, persists project state, and serves the web and iOS clients.

Host and clients

The host is the center of an ACPDash installation. It serves the built React web application, handles HTTP and live event connections, and runs the agent runtime. The native iOS application is a separate client of the same host.

Web dashboard / iOS client
            │
      HTTP + live events
            │
       ACPDash host
      ┌─────┼────────────┐
      │     │            │
   SQLite   Agent        Git worktrees
   state    runtime      and commands
            │
       ACP adapters
            │
      Agent providers
            │
    Per-agent MCP tools
            │
      Host services

The agent provider owns its model behavior and system prompts. ACPDash supplies operation-specific context: the project, role, approved scope, user feedback, attachments, and recovery state.

Durable state

SQLite stores projects, agents, conversations, workflow revisions, requests, artifact metadata, and evidence. Files for uploads and proof live alongside the database in a content/ directory.

The host persists provider and application events, then delivers them to active clients. Durable state lets it reconstruct sessions and reconcile unfinished work after a restart.

Chat is the conversation and steering interface. Plans, issue revisions, decisions, attachments, and proof are separate workflow records. A conversation label and a running process state also represent different things: an idle process can still belong to unfinished work.

Agent workspaces

Each child receives its own conversation and Git worktree. Its branch starts from the revision selected by the workflow. Independent work can proceed without sharing uncommitted changes, while dependent work starts from an accepted prerequisite’s tested head or an updated base branch.

The per-agent MCP endpoint scopes dashboard tools to that agent. Tool calls go through host services for project state, coordination, commands, and proof. Agents should not read or edit the dashboard database directly.

Preview isolation

HTML artifacts and live previews use a separate origin. Remote preview configuration needs a client-reachable origin with a different hostname from the dashboard. A different port on the same hostname is insufficient.

The dashboard has no built-in login. Keep it on a trusted private network or put an authenticated reverse proxy in front of it. See remote access for the connection requirements.

Source map

Area	Repository path
HTTP host and routes	`src/host/server.ts`
State and persistence	`src/host/store.ts`
Agent lifecycle	`src/host/runtime.ts`
Plans and issue execution	`src/host/workflow.ts`
Agent MCP tools	`src/host/mcp.ts`
Pinned closeout policy	`src/host/closeout-policy.ts`
Command retry counts and recovery	`src/host/closeout-attempts.ts`
Portable preflight guide	`src/host/closeout-instructions.ts`, `scripts/package-preflight.ts`
Briefings and operation prompts	`src/host/briefing.ts`, `src/host/workflow-guidance.ts`
Provider transport	`src/host/acp-session.ts` and provider modules
Attachments and artifacts	`src/host/content.ts`
Preview service	`src/host/preview.ts`
React web client	`src/web/`
Native client	`ios/`
Public website and these docs	`website/`

Repository agent workflow rules live in AGENTS.md. Skill entry points refer to that guide instead of duplicating its policy into every prompt.

The host’s get_closeout_instructions tool reads the marked preflight section of that guide. The service installers package the same text for local discovery. Command failure counts are durable state tied to the issue revision, pinned policy, command item, and retry round; they survive host restarts.