# Local install (M1 alpha)

Downloadable / single-machine Browser Pilot. **Local mode only** — binds `127.0.0.1`, no public screenshot path. See `docs/privacy-architecture.md`.

## Requirements

- Node.js 20+
- Chrome (or Chromium) with ability to load unpacked extensions
- This repo built once: `pnpm install && pnpm build`

## One-time setup

```bash
cd /path/to/browser-pilot
pnpm install
pnpm build
pnpm bp bootstrap   # tokens + Claude/Cursor mcp.json
pnpm bp start       # local server
pnpm bp doctor      # checklist
```

### Extension (required for any browser control)

1. Chrome → `chrome://extensions`
2. Enable **Developer mode**
3. **Load unpacked** → select `extension-dist/` from this repo
4. Open the Browser Pilot popup; set values printed by `bp bootstrap` (also in `~/.browser-pilot/local-credentials.json`):
   - Browser ID: `default`
   - WS URL: `ws://127.0.0.1:3200`
   - HTTP URL: `http://127.0.0.1:3201`
   - Extension token: `bpx_…`
5. Restart your Claude/Cursor session (MCP config is read at session start)
6. Agent: `browser_status` → your profile listed

## Daily use

```bash
pnpm bp start
pnpm bp status
# … agents drive Chrome …
pnpm bp stop
```

## CLI reference

| Command | What |
|---|---|
| `bp bootstrap` | Mint/reuse local tokens; write Claude + Cursor MCP entries; print extension steps |
| `bp start` | Start server with `BP_DEPLOYMENT_MODE=local` |
| `bp stop` | SIGTERM the pid in `~/.browser-pilot/run/server.pid` |
| `bp status` | Pid + `/health` + `/privacy` |
| `bp doctor` | Binary, proxy, extension-dist, process, privacy, creds, mcp.json |

## What users should expect (concrete bar)

- After install + extension load, an agent can call `browser_status` and see **this machine’s** Chrome
- Server listens only on loopback (`ss` / `bp doctor` privacy bind = `127.0.0.1`)
- Screenshots do not get a public viewer URL in local mode

## Alpha package script

```bash
bash scripts/package-local-alpha.sh
# → dist-local-alpha/ with extension, server, proxy, README
```

## Flow packs (M2)

Shared playbooks (no screenshots/cookies):

```bash
pnpm pack:export ./my-pack          # sanitize export from local store
pnpm bp pack pull ./my-pack         # merge into this machine (additive)
pnpm bp pack status
# Or: bp pack pull https://cdn.example/bp-pack/stable
# Auto-pull on start when set:
#   BP_PACK_URL=https://cdn.example/bp-pack/stable pnpm bp start
```

Seed packs can ship inside alpha packages under `seed-pack/`.

### Contribute / promote (M3, opt-in)

**Default off.** Enabling does not grant remote browser control — promote tokens are separate from MCP tokens and can only POST sanitized flow JSON.

```bash
bp pack contribute on
bp pack promote some/flow-id --dry-run   # print payload; nothing leaves disk
bp pack promote some/flow-id             # stage under ~/.browser-pilot/promote-queue/
# optional: BP_PACK_PROMOTE_URL=https://…  # POST staged payload with promote token
bp pack contribute off
bp pack status                           # contributeEnabled, uploads24h
```

## Not this path

Hetzner multi-user fleet stays on `systemctl` + `BP_DEPLOYMENT_MODE=fleet`. Do not use `bp start` on the operator host for production fleet traffic.
