> ## 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 configuration reference

> Reference for every Fleet Pi environment variable — LLM provider keys, Pi runtime, logging, auth, and the Neon Postgres chat session mirror.

Fleet Pi loads configuration from `.env` at the repo root, then `.env.local` (`.env.local` takes precedence). The dev server is responsible for loading these files into the server-side routes; values are accessed through `process.env` at runtime. Credentials saved from the in-app Configurations panel are written to `.env.local`.

The canonical example lives in [`.env.example`](https://github.com/Qredence/fleet-pi/blob/main/.env.example). This page is the authoritative reference for every variable Fleet Pi reads, grouped by concern.

## LLM providers

Fleet Pi defaults to Google Gemini with the `gemini-3.5-flash` model. Pi settings store the active provider and model, and you can change both from the in-app config panel. The same panel manages provider API keys and writes them to `.env.local`.

| Provider       | Provider ID      | API key variable                  |
| -------------- | ---------------- | --------------------------------- |
| Google Gemini  | `google-genai`   | `GEMINI_API_KEY`                  |
| Amazon Bedrock | `amazon-bedrock` | `AWS_ACCESS_KEY_ID` (+ AWS chain) |
| OpenAI         | `openai`         | `OPENAI_API_KEY`                  |
| Anthropic      | `anthropic`      | `ANTHROPIC_API_KEY`               |
| Google Vertex  | `google-vertex`  | `GOOGLE_APPLICATION_CREDENTIALS`  |
| Mistral        | `mistral`        | `MISTRAL_API_KEY`                 |
| Groq           | `groq`           | `GROQ_API_KEY`                    |
| Ollama         | `ollama`         | `OLLAMA_BASE_URL`                 |

### Amazon Bedrock

When using Bedrock, Fleet Pi uses the standard AWS credential chain — environment variables, profile, or IAM role.

Fleet Pi defaults to **Google Gemini** (`gemini-3.5-flash`). The default provider and model are set in `.pi/settings.json`:

```json theme={null}
{
  "defaultProvider": "google",
  "defaultModel": "gemini-3.5-flash"
}
```

Change those fields to switch the default provider; set the matching API key in `.env` (or via the in-app config panel). Every provider supported by Pi is available — pick whichever credentials you already have.

| Provider         | `defaultProvider` value | Credential variable                                               |
| ---------------- | ----------------------- | ----------------------------------------------------------------- |
| Google Gemini    | `google`                | `GEMINI_API_KEY`                                                  |
| Google Vertex AI | `google-vertex`         | `GOOGLE_APPLICATION_CREDENTIALS` (path to a service account)      |
| OpenAI           | `openai`                | `OPENAI_API_KEY`                                                  |
| Anthropic        | `anthropic`             | `ANTHROPIC_API_KEY`                                               |
| Amazon Bedrock   | `amazon-bedrock`        | Standard AWS credential chain (`AWS_PROFILE`, env vars, IAM role) |
| Mistral          | `mistral`               | `MISTRAL_API_KEY`                                                 |
| Groq             | `groq`                  | `GROQ_API_KEY`                                                    |
| Ollama           | `ollama`                | `OLLAMA_BASE_URL`                                                 |

### Amazon Bedrock (opt-in)

When `defaultProvider` is `amazon-bedrock`, Fleet Pi uses the standard AWS credential chain:

| Variable                   | Required | Default     | Purpose                                                               |
| -------------------------- | -------- | ----------- | --------------------------------------------------------------------- |
| `AWS_REGION`               | No       | `us-east-1` | Region for every Bedrock call. Models must be enabled in this region. |
| `AWS_PROFILE`              | No       | —           | Use a named AWS profile from `~/.aws/credentials`.                    |
| `AWS_BEARER_TOKEN_BEDROCK` | No       | —           | Set only if your Bedrock setup uses bearer-token authentication.      |

You can also provide `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` directly. Bedrock model IDs use region prefixes such as `us.anthropic.claude-sonnet-4-6`.

## Pi runtime

| Variable                  | Required | Default    | Purpose                                                                                       |
| ------------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------- |
| `PI_AGENT_DIR`            | No       | Pi default | Override the Pi agent resource directory. Read in `server-runtime.ts` and `server-shared.ts`. |
| `FLEET_PI_RUNTIME_TTL_MS` | No       | `600000`   | How long a Pi runtime stays warm between chat turns (10 minutes by default).                  |
| `FLEET_PI_REPO_ROOT`      | No       | `cwd`      | Override the project root that the workspace server treats as canonical.                      |

## Logging

| Variable    | Required | Default | Purpose                                                               |
| ----------- | -------- | ------- | --------------------------------------------------------------------- |
| `LOG_LEVEL` | No       | `info`  | Pino log level. Logs are pretty-printed unless `NODE_ENV=production`. |
| `NODE_ENV`  | No       | —       | Controls pretty-printing and a few Vite behaviors.                    |

The logger lives in [`apps/web/src/lib/logger.ts`](https://github.com/Qredence/fleet-pi/blob/main/apps/web/src/lib/logger.ts). It includes PII redaction and emits a `requestId` correlation ID for every chat request, which lines up with provider circuit-breaker events for incident review.

## Authentication (Better Auth)

Auth is **disabled** until you set `BETTER_AUTH_SECRET`. When the secret is present, Better Auth is mounted at `/api/auth/*`. The auth store can be local SQLite (default) or Neon Postgres.

| Variable                               | Required when auth enabled | Default                 | Purpose                                                                    |
| -------------------------------------- | -------------------------- | ----------------------- | -------------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET`                   | Yes                        | —                       | Signing secret. Generate with `openssl rand -base64 32`.                   |
| `BETTER_AUTH_URL`                      | No                         | `http://localhost:3000` | Base URL used for OAuth callback URLs.                                     |
| `BETTER_AUTH_TRUSTED_ORIGINS`          | No                         | `BETTER_AUTH_URL`       | Comma-separated list of trusted origins for the auth router.               |
| `AUTH_DATABASE_PATH`                   | No                         | `.fleet/auth.sqlite`    | SQLite database path used when Neon auth is not configured.                |
| `FLEET_PI_AUTH_DATABASE_URL`           | No                         | —                       | Neon Postgres connection string (app role — DML only) for the auth DB.     |
| `FLEET_PI_AUTH_MIGRATION_DATABASE_URL` | For migrations             | —                       | Direct `neondb_owner` connection used by `pnpm --filter web auth:migrate`. |
| `GOOGLE_CLIENT_ID`                     | No                         | —                       | Enables Google OAuth when paired with `GOOGLE_CLIENT_SECRET`.              |
| `GOOGLE_CLIENT_SECRET`                 | No                         | —                       | Required with `GOOGLE_CLIENT_ID`.                                          |

The Google login button is hidden in the UI when either Google variable is missing. When `FLEET_PI_AUTH_DATABASE_URL` is set, Better Auth uses Neon instead of local SQLite — apply schema once per environment with `pnpm --filter web auth:migrate`.

## Sessions and workspace paths

Pi session files are persisted under `.fleet/sessions/` inside the repo. The session manager rejects paths outside the repo-scoped directory via `isUsableSessionFile`, so a stale `sessionFile` in `localStorage` silently falls back to a fresh session — see [runbooks](/fleet-pi/runbooks#ir-2-chat-session-corruption-or-data-loss) for recovery.

Canonical durable state lives under `agent-workspace/`. The workspace server reads canonical files directly and uses `agent-workspace/indexes/` only as projection storage.

## Chat session mirror (Neon Postgres)

Pi session JSONL files under `.fleet/sessions/` are always the source of truth. When `FLEET_PI_CHAT_DATABASE_URL` is set, Fleet Pi additionally mirrors full Pi session entries, run events, tool executions, and file mutations into Neon Postgres tables prefixed with `pi_`. Use this when you want SQL search across conversations, cross-surface history, analytics, or long-term debugging.

Mirror failures are caught and logged — they never break chat streaming.

| Variable                               | Required       | Default | Purpose                                                                                         |
| -------------------------------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `FLEET_PI_CHAT_DATABASE_URL`           | No             | —       | Enables the mirror. Pooled Neon connection string for the runtime app role (DML only).          |
| `FLEET_PI_CHAT_MIGRATION_DATABASE_URL` | For migrations | —       | Direct `neondb_owner` connection string used by `pnpm chat:migrate` to apply schema migrations. |

Use two separate roles in Neon:

| Role           | Privileges                                      | Used by             |
| -------------- | ----------------------------------------------- | ------------------- |
| `neondb_owner` | Full DDL + DML (CREATE, ALTER, DROP, etc.)      | Migration CLI only  |
| `fleet_pi_app` | SELECT, INSERT, UPDATE, DELETE on `pi_*` tables | Running application |

Apply migrations once per environment before starting the app:

```bash theme={null}
pnpm --filter web chat:migrate
```

See [runbooks](/fleet-pi/runbooks#chat-session-mirror-neon-postgres) for the full table list and operational guidance.

## Daytona-backed user sandboxes

Authenticated users can be assigned isolated Daytona sandboxes for cross-surface preview and tool execution. Sandboxes are gated by Better Auth — without auth, the sandbox routes return `401`.

| Variable                 | Required                | Default             | Purpose                                                                                                                                    |
| ------------------------ | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `DAYTONA_API_KEY`        | Yes (to enable Daytona) | —                   | Enables the Daytona-backed user sandbox path. When unset, `GET /api/sandbox/preview` returns `503`.                                        |
| `DAYTONA_API_URL`        | No                      | Daytona SDK default | Override the Daytona API base URL (for example, self-hosted Daytona).                                                                      |
| `DAYTONA_TARGET`         | No                      | —                   | Optional Daytona target region or pool identifier.                                                                                         |
| `DAYTONA_WEBHOOK_SECRET` | No                      | —                   | Shared secret expected in the `x-daytona-signature` header for `POST /api/webhooks/daytona`. Without it, webhook side effects are ignored. |

See the [API reference](/fleet-pi/api-reference#sandbox) for the sandbox preview and webhook contracts.

## Generated configuration files

| File                            | Purpose                                                                                                                |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `apps/web/src/routeTree.gen.ts` | Generated by TanStack Router. **Do not edit by hand.**                                                                 |
| `openapi.json`                  | Generated from zod schemas, drives the [API reference](/fleet-pi/api-reference). Regenerate with `pnpm generate:docs`. |
| `agent-workspace/manifest.json` | Describes the canonical workspace shape and the contract version.                                                      |

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/fleet-pi/quickstart">
    Apply this configuration end to end.
  </Card>

  <Card title="Runbooks" icon="life-ring" href="/fleet-pi/runbooks">
    Troubleshoot provider errors, sessions, and circuit-breaker state.
  </Card>
</CardGroup>