> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fleet Pi quickstart

> Install Fleet Pi with pnpm, configure a Google Gemini API key, and launch the local Pi-backed chat workspace in under five minutes.

Get Fleet Pi running locally with Pi-backed chat and repo-scoped tools.

## Prerequisites

* **Node.js 22 or newer** — [nodejs.org](https://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.

<Tip>
  Enable Corepack once so the pinned pnpm version is used automatically:

  ```zsh theme={null}
  corepack enable
  corepack prepare pnpm@10.33.3 --activate
  ```
</Tip>

## 1. Clone and install

```zsh theme={null}
git clone https://github.com/Qredence/fleet-pi.git
cd fleet-pi
pnpm install
```

## 2. Create local configuration

```zsh theme={null}
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](/fleet-pi/configuration) 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.

<Note>
  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.
</Note>

## 3. Start the app

```zsh theme={null}
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000).

## 4. Smoke check

In a second terminal:

```zsh theme={null}
curl http://localhost:3000/api/health
```

Expected response:

```json theme={null}
{ "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](/fleet-pi/runbooks#circuit-breaker-states).
* You do not need the Codex desktop app or the advanced Codex worktree flow.

## Optional: enable authentication

Fleet Pi ships with [Better Auth](https://www.better-auth.com/) and an embedded SQLite database. Auth is disabled until you set a secret:

```zsh theme={null}
# 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

```zsh theme={null}
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

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/fleet-pi/configuration">
    Every environment variable Fleet Pi reads.
  </Card>

  <Card title="Chat modes" icon="sliders-vertical" href="/fleet-pi/chat-modes">
    Agent, Plan, and Harness — and the tools each one allows.
  </Card>

  <Card title="Agent workspace" icon="folder-tree" href="/fleet-pi/agent-workspace">
    Learn how durable memory, plans, and Pi resources live in Git.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/fleet-pi/architecture">
    Browser client, TanStack Start backend, and agent workspace boundaries.
  </Card>
</CardGroup>