Local Stack

The ignored config/local-stack.json file is the canonical machine-local configuration. The tracked config/local-stack.example.json contains safe placeholders, and config/local-stack.schema.json describes the same contract used by the launcher.

Top-level Fields

Field	Purpose
`mode`	`development` for bind-mounted watchers or `production` for built images
`persistence`	Preserve named volumes or use disposable local data
`codex`	Agent authentication mode and source
`workerReplicas`	Number of task-worker service replicas
`ports`	Host ports for infrastructure and applications
`postgres`	Local database name and credentials
`garage`	Local S3-compatible storage settings
`agentServiceToken`	Backend authentication for trusted agent runtimes
`integrationCredentialKey`	Encryption key for integration credential envelopes
`googleOAuth`	Optional Google client credentials

Mode

development mounts source and runs watchers. production builds and runs the service-owned images. This is an image/runtime mode, not a complete production deployment guide.

Persistence

Use persistent to keep named volumes across normal stop/start cycles. Use disposable behavior only when losing local database, Redis, object-store, and Codex container state is intended.

Codex

Field	Meaning
`authMode`	`local` or `api-key`
`localHome`	Host Codex home used only to locate `auth.json` in local mode
`apiKeyEnvironmentVariable`	Name of the host variable read in API-key mode

Ports

Each port is a host binding. Containers use Compose service names and their internal service ports. Do not reuse a host loopback URL inside a container.

PostgreSQL

Set a local user, password, and database. PostgreSQL with pgvector is the canonical operational store. Migrations run as a one-shot startup dependency.

Garage

Garage provides the supported local S3-compatible service. The application remains provider-neutral and consumes the S3 environment contract. Configure region, bucket, access key, secret key, RPC secret, admin token, and metrics token.

Integration Credential Key

The value must satisfy the schema’s base64 key contract. Changing it after credentials have been stored makes existing credential envelopes unreadable; disconnect or migrate integrations before rotating it.

Google OAuth

When googleOAuth is present, the generator writes the Google client values, local callback URI, and frontend return URL. Omit the block when Google Workspace is not needed.

Managed MCP OAuth

The generator always writes the local managed-MCP callback URI and frontend return URL. Providers such as Apollo discover their authorization server and dynamically register the local client, so no provider client secret belongs in local-stack.json.

Production deployments must set MCP_OAUTH_REDIRECT_URI to the public backend callback at /oauth/mcp/callback and FRONTEND_URL to the public product origin. The callback URI registered by the provider must match exactly.

Generate Runtime Files

bun run stack env

This generates complete environment files for the backend, frontend, chat agent, worker agent, and containers. Edit the JSON input rather than the generated files.

Inspect Before Starting

bun run stack config

Use this after changing ports, persistence, replicas, authentication, or local infrastructure credentials.

Lifecycle Commands

bun run stack up
bun run stack ps
bun run stack logs -f
bun run stack down

Read-only commands such as ps, logs, and config should not rewrite environment files or trigger watcher restarts.

Reset Local Data

bun run stack reset --confirm

This removes local stack volumes. Use it only when the loss of local state is acceptable.

Developers adding a field should follow Local Stack and Migrations.

On this page