Fleet Pi configuration reference - Qredence Documentation

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. 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:

{
  "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. 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 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:

pnpm --filter web chat:migrate

See runbooks 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 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. Regenerate with `pnpm generate:docs`.
`agent-workspace/manifest.json`	Describes the canonical workspace shape and the contract version.

Quickstart

Apply this configuration end to end.

Runbooks

Troubleshoot provider errors, sessions, and circuit-breaker state.

​LLM providers

​Amazon Bedrock

​Amazon Bedrock (opt-in)

​Pi runtime

​Logging

​Authentication (Better Auth)

​Sessions and workspace paths

​Chat session mirror (Neon Postgres)

​Daytona-backed user sandboxes

​Generated configuration files

​Related