Local Stack and Migrations

Add a Configuration Field

1. Add the field to the schema in scripts/stack.ts.
2. Add a complete safe placeholder to config/local-stack.example.json.
3. Update config/local-stack.schema.json when the generated schema is tracked separately.
4. Map it to every required host and container environment file.
5. Update the consuming app’s environment validator.
6. Represent optional values explicitly only where the schema maps empty to undefined.
7. Add stack-generator tests.
8. Update Local Stack.

Generated environment files are outputs. Do not add another local environment contract or ask operators to edit generated files.

Public local-stack URLs must be HTTPS and structurally exact: the frontend value is an origin, and provider callbacks use their owned callback paths. Keep public browser/provider URLs separate from internal BACKEND_URL values. A Vite public origin must produce one explicit allowed hostname; never use an unrestricted host allowlist.

Reverse proxies remain external deployment infrastructure. Do not add tunnel credentials or a cloudflared service to the local stack without a separate architecture milestone. Document WebSocket forwarding and the lack of an end-user authentication gate whenever public local testing is supported.

Add a Container Service

• Keep the Dockerfile with the owning app.
• Add a health check.
• Wait for healthy infrastructure and one-shot migrations.
• Use Compose DNS names inside containers.
• Make persistent/disposable lifecycle explicit.
• Add bounded idempotent shutdown.
• Log startup, shutdown, failures, and recovery—not every healthy tick.

Agent images use the Debian/glibc Bun base with CA certificates and required shell tooling. Do not move Codex execution to Alpine without proving binary and TLS compatibility.

Codex Credential Synchronization

Local authentication has one deployment-scoped host-credential writer. codex-auth-sync alone mounts the host auth.json and the shared codex_state volume. It validates last_refresh, installs only a strictly newer generation with an atomic mode-0600 rename, and publishes a readiness marker before chat or worker startup. Invalid source or active files fail closed.

The service watches the host file and also scans at codex.authSyncIntervalSeconds, which defaults to 60 seconds and accepts 10–86,400. Keep the interval in the canonical JSON config, generated Compose environment, runtime validator, tests, and user reference together.

Agent executions do not poll credentials. A Codex-auth failure writes a synchronization request marker and waits briefly for a new generation. The adapter retries once only before any item.started, item.updated, or item.completed event. Never replay after an item event, on cancellation, or without proof that the generation advanced.

Add a Migration

1. Update shared and app-local typed contracts.
2. Change schema enums, tables, and relationships in their owning modules.
3. Generate the migration and snapshot.
4. Inspect generated SQL.
5. Update repositories and lifecycle services.
6. Update endpoint validators and OpenAPI.
7. Add migration and repository tests.
8. Verify upgrade behavior against existing state.

Do not edit an already-applied migration to represent a new schema change.

Add a Pinned Vendor Binary

Install it during the owning image build with an exact version and per-architecture checksum. Keep integration binaries below their provider-owned directory and off the global path. Rebuild and verify every affected image.