Skip to main content
Get Fleet Pi running locally with Pi-backed chat and repo-scoped tools.

​
Prerequisites

  • Node.js 22 or newer — nodejs.org
  • pnpm 10.33.3 — matches the pinned packageManager field in package.json
  • An LLM provider API key — Fleet Pi defaults to Google Gemini (gemini-3.5-flash). Amazon Bedrock, OpenAI, Anthropic, Google Vertex, Mistral, Groq, and Ollama are also supported.
The default provider is google and the default model is gemini-3.5-flash. Set GEMINI_API_KEY to use the default, or switch providers in the in-app config panel.
Enable Corepack once so the pinned pnpm version is used automatically:
corepack enable
corepack prepare pnpm@10.33.3 --activate

​
1. Clone and install

git clone https://github.com/Qredence/fleet-pi.git
cd fleet-pi
pnpm install

​
2. Create local configuration

cp .env.example .env
The dev server loads .env from the repo root, then .env.local (.env.local wins) for server-side routes. The checked-in example only contains public-safe knobs. See the configuration reference for every supported variable. Typical first-run choices:
  • Set GEMINI_API_KEY to use the default Google Gemini provider.
  • To use a different provider, set its API-key env var (OPENAI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, OLLAMA_BASE_URL) or AWS credentials for Bedrock. Then select the provider in the in-app config panel.
  • Leave PI_AGENT_DIR unset unless you want a non-default Pi agent resource directory.
Provider keys can also be entered in the in-app config panel, which writes them to .env.local. The active provider and model are stored in Pi settings.

​
3. Start the app

pnpm dev
Open http://localhost:3000.

​
4. Smoke check

In a second terminal: 
curl http://localhost:3000/api/health
Expected response: 
{ "status": "ok" }
Then send a simple prompt like read package.json in the chat UI and confirm that a read tool card appears in the transcript.

​
What “standalone” means

Standalone does not mean “without Pi” or “without an LLM provider.” It means:
  • You run Fleet Pi locally as a normal pnpm web app.
  • The bundled Pi runtime (@earendil-works/pi-coding-agent) powers chat and tool execution.
  • The backend still expects a working LLM provider — every model call goes through the circuit breaker.
  • You do not need the Codex desktop app or the advanced Codex worktree flow.

​
Optional: enable authentication

Fleet Pi ships with Better Auth and an embedded SQLite database. Auth is disabled until you set a secret: 
# in .env
BETTER_AUTH_SECRET=$(openssl rand -base64 32)
BETTER_AUTH_URL=http://localhost:3000
Google OAuth becomes available when GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are both set. The auth database defaults to .fleet/auth.sqlite; override with AUTH_DATABASE_PATH.

​
Useful commands

pnpm dev                    # start the dev server
pnpm typecheck              # TypeScript across the workspace
pnpm lint                   # ESLint
pnpm --filter web test      # Vitest unit tests (incl. circuit breaker)
pnpm e2e                    # Playwright end-to-end tests
pnpm build                  # production build
pnpm validate-agents-md     # validate AGENTS.md files
pnpm generate:docs          # regenerate API + architecture + project-structure docs
pnpm knip                   # detect unused exports
pnpm syncpack               # verify dependency version alignment

​
Next steps

Configuration

Every environment variable Fleet Pi reads.

Chat modes

Agent, Plan, and Harness — and the tools each one allows.

Agent workspace

Learn how durable memory, plans, and Pi resources live in Git.

Architecture

Browser client, TanStack Start backend, and agent workspace boundaries.