Requirements
What the local Oblive stack expects from the host and how to choose an agent authentication mode.
Host Tools
You need:
- Bun matching the repository package-manager declaration.
- Docker with the Compose plugin.
- Git to check out and update the repository.
- Enough local disk for container images, PostgreSQL, Redis persistence, object storage, and agent workspaces.
- Free ports for the configured services.
Verify the two critical tools:
bun --version
docker compose versionAgent Authentication
Choose one mode in config/local-stack.json.
Local Codex login
Use "authMode": "local" when the host already has a working Codex login. Oblive reads only the
host auth.json during setup and seeds it into a container-owned Codex volume. It does not mount
your host Codex home, sessions, plugins, configuration, or global skills.
The configured localHome supports ~ in the machine-local JSON file.
OpenAI API key
Use "authMode": "api-key" and set the environment variable named by
apiKeyEnvironmentVariable before generating or starting the stack.
export OPENAI_API_KEY="your-key"Do not put the API key in the tracked example, Compose file, generated documentation, or source control.
Default Ports
| Service | Default Port | Purpose |
|---|---|---|
| Backend | 3000 | HTTP API, health, and local API reference |
| Frontend | 3001 | Oblive product interface |
| PostgreSQL | 5432 | Canonical operational state and pgvector |
| Redis | 6379 | Live signals and worker wakeups |
| Garage S3 | 3900 | Local S3-compatible object API |
| Garage admin | 3903 | Local storage administration |
Change a host port in local-stack.json if it conflicts. Container-to-container services continue
to use Compose DNS names rather than host loopback addresses.
Optional Integration Requirements
Google Workspace requires a Google OAuth client ID and client secret in googleOAuth. Other managed
providers are configured after onboarding from the Integrations screen.
Expected Result
You can run bun install and docker compose version successfully, your selected authentication
mode is available, and the configured host ports are free.