Documentation / v0.1

Build with evidence,
not guesswork.

A practical guide to the AIPI companion, dashboard, MCP tools, logs, and the local-first data boundary.

01 · Architecture

Cloud-rendered. Locally executed.

The website and dashboard shell are delivered from Cloudflare. When you open AIPI, your browser connects directly to the companion at 127.0.0.1:49152. Repository scans, API calls, response bodies, credentials, logs, and evidence never need to leave your machine.

Cloudflare UI→Browser→Local companion→Repository + APIs

02 · Commands

The commands you need.

The companion is published on the public npm registry. Run this first command from the project root; it configures the project, IDE integrations, local daemon, and dashboard in one pass.

npx @vmise/aipi-companion@latest initDetect source roots, write .aipirc.json, configure Codex, Cursor, and VS Code, register the project, and open the connected dashboard.

npx @vmise/aipi-companion@latest openStart or reuse the daemon and open the authenticated local dashboard later.

aipi pairCreate a short-lived outbound pairing session for the hosted dashboard after sign-in.

aipi daemonRun the loopback dashboard server directly when you need a persistent local engine.

aipi mcpRun the thin stdio MCP client; it reuses or starts the daemon.

03 · Local session

Authenticated without a cloud URL secret.

The default dashboard shares the loopback origin with the companion, avoiding browser Private Network Access failures.

1. daemon startsCreates a cryptographically random session secret and binds only to 127.0.0.1.

2. local launchaipi open opens the loopback /launch route for the selected project.

3. HTTP-only cookieThe launch route creates a SameSite local session and redirects to the dashboard.

4. authenticated callsSame-origin requests include the local session automatically; protected API routes reject missing or invalid credentials.

5. hosted pairingaipi pair uses a separate ten-minute outbound WebSocket session when the hosted dashboard is required.

WHAT CLOUDFLARE SEES

The public site and paired UI transport only. Cloudflare does not receive repository files, credentials, API request/response data, logs, or evidence.

04 · MCP setup

Give your agent a local evidence layer.

Add AIPI to your MCP client. The server uses stdio, so the agent can request repository-aware discovery, diagnosis, and verification without exposing a listening MCP endpoint.

{
  "mcpServers": {
    "aipi": {
      "command": "aipi",
      "args": ["mcp"]
    }
  }
}

05 · Dashboard

Read the signal, then act.

MAP

Trace the contract

See consumers, routes, validators, schemas, migrations, and tests connected by source locations.

LOGS

Keep the useful history

Review failed runs, agent activity, new APIs, project changes, and concise diagnosis summaries.

EVIDENCE

Understand the why

Every finding carries confidence, detection method, and the files that support it.

HANDOFF TO YOUR AGENT

Open a failed Log and choose Copy handoff. Or ask your IDE agent to call get_latest_handoff through MCP. AIPI owns evidence and verification; your agent owns code changes.

06 · Troubleshooting

When the dashboard says disconnected.

Check the daemon

Run aipi doctor or aipi open. Confirm that http://127.0.0.1:49152/health responds. If that port is busy, AIPI automatically tries the next ports through 49160.

Refresh the session

Close the dashboard tab and run aipi open again. AIPI creates a fresh same-origin local session.

IDE cannot find MCP

Run aipi init again from the project root. It writes the aipi entry to local Cursor and VS Code MCP configuration. Restart the IDE after changing its MCP settings.

Need the hosted dashboard

Sign in and use aipi pair. The companion connects outward through the short-lived relay, so the hosted page never needs browser access to localhost.

Build with evidence,not guesswork.