Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.protean.peerislands.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Prereqs

  • macOS or Linux. Bun ≥ 1.1. Git.
  • Optional: gh CLI (for repo ops), az CLI (for Microsoft 365 OAuth registration).

​
Install

git clone https://github.com/PeerIslands-PeerAI/protean.git
cd protean
bun install

​
Generate session secrets

bun run scripts/setup-jwt.ts --force
Writes JWT_SECRET + JWT_REFRESH_SECRET to .env. Never echoes the values.

​
Register an OAuth provider (pick one)

GitHub is fastest: 
bun run scripts/setup-oauth.ts --provider github
Walks you through the GitHub OAuth App registration, prompts for paste-back, atomically updates .env. See ops/integrations for Google + Microsoft 365.

​
Boot

# terminal 1
bun run --filter @protean/api dev          # http://localhost:8000

# terminal 2
bun run --filter @protean/web dev          # http://localhost:5173
Visit http://localhost:5173/login and click Continue with GitHub. You should land back on the callback with a protean_session cookie set.

​
Try the CLI

bun run apps/cli/src/bin.ts health         # SDK → API round-trip
bun run apps/cli/src/bin.ts code --help    # delegates to pi-coding-agent
See reference/cli for the full surface.

​
Run the replay gate

bun run --filter @protean/e2e test:replay  # the determinism gate
This is the load-bearing CI gate. A “hello” agent runs deterministically; the event sequence must match the recorded cassette byte-for-byte.

​
Where next