Requirements

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 version

Agent 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 mounts only the host auth.json into a dedicated synchronizer, which keeps the container-owned Codex volume on the latest valid generation. It does not mount your host Codex home, sessions, plugins, configuration, or global skills.

The configured localHome supports ~ in the machine-local JSON file. authSyncIntervalSeconds controls the fallback scan and defaults to 60 seconds; file changes are normally detected immediately.

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

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. Meta Ads requires a Meta-approved OAuth client ID in metaAdsOAuth; it does not use a client secret. Direct Marketing API operations use the same resulting organization token. Organic X requires an OAuth 2.0 client ID in xOAuth; Web Apps, Automated Apps, and Bots also use the optional client secret, while Native Apps and SPAs omit it. X Ads is separate and requires Ads API access plus an OAuth 1.0a consumer key and secret in xAdsOAuth. Other managed providers are configured after onboarding from the Integrations screen.

Meta does not accept a localhost callback for this setup. Local Meta connection testing therefore also needs an externally managed HTTPS reverse proxy with an app hostname routed to port 3001 and an API hostname routed to port 3000. The app route must support WebSockets for development HMR. Cloudflare Tunnel is one option, but Oblive does not install or manage it.

Protect both public hostnames with an external access policy. The local control plane has no end-user authentication gate and is unsafe behind an unrestricted public tunnel.

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.

Next

Install Oblive.