Install Oblive

Quick Install

Run the installer on macOS or Linux:

curl -fsSL https://oblive.dev/install.sh | sh

The interactive flow checks the host, offers missing prerequisites, verifies Codex login, downloads and verifies the release checksum and deployment bundle, creates a secure configuration, and starts every service. It also offers to add the oblive command to your PATH; pressing Enter accepts this recommended default.

To review the installer before running it:

curl -fsSL https://oblive.dev/install.sh -o /tmp/oblive-install.sh
less /tmp/oblive-install.sh
sh /tmp/oblive-install.sh

Latest or a Selected Version

The default latest channel resolves the current stable version from downloads.oblive.dev during installation. Oblive then records and runs that exact semantic version across the backend, frontend, agents, and deployment bundle. Starting the stack never changes the installed version.

Pin a selected stable version with:

curl -fsSL https://oblive.dev/install.sh | sh -s -- --version v1.2.3

Both 1.2.3 and v1.2.3 are accepted. Pre-release versions are rejected.

Run Multiple Instances on One Computer

Give each additional installation a name and six unused consecutive host ports:

curl -fsSL https://oblive.dev/install.sh | sh -s -- --instance preview --port-base 10000
curl -fsSL https://oblive.dev/install.sh | sh -s -- --instance demo --port-base 11000

These commands create independent stacks. preview opens at http://127.0.0.1:10005 and demo at http://127.0.0.1:11005. An existing default installation stays at its configured address, normally http://127.0.0.1:3001. Add --version vX.Y.Z to pin either instance to a supported release; instances can run the same version or different versions.

oblive instances
oblive --instance preview status
oblive --instance preview stop
oblive --instance preview start --no-open
oblive --instance demo update

The selector goes before the command. Commands without a selector operate on default; oblive --instance default start selects it explicitly. Installing a named instance does not change the default installation. If you installed only named instances, always select one.

Names contain up to 48 lowercase letters, digits, dashes, or underscores, starting with a letter or digit. Named installations live at ~/.oblive-instances/<name> unless --install-dir is supplied. Their configurations, database, files, networks, and container-owned Codex state are independent. The name stays fixed when you update the release.

--port-base must be between 1024 and 65530. Its six ports map, in order, to PostgreSQL, Redis, Garage S3, Garage admin, backend, and frontend. Choose ranges that do not overlap another instance or another application; ports are not selected automatically. Reinstalling an existing instance reuses its directory and configuration, so --port-base can be omitted. Change existing ports through oblive --instance <name> config edit.

Named instances require releases that support them. The installer rejects older bundles that would operate the default Compose project. Each running instance consumes its own infrastructure and worker resources; set workerReplicas in its configuration to fit your computer.

For public access, give each instance its own public origins and OAuth callbacks. Compose-managed Cloudflare tunnels can be configured per instance with separate tunnel credentials. Host-managed Cloudflared remains one shared host service whose routes you manage separately.

Authentication

The default local mode uses your Codex CLI login. For API-key mode, provide the configured host environment variable while installing and whenever Oblive starts or checks authentication:

export OPENAI_API_KEY="your-key"
curl -fsSL https://oblive.dev/install.sh | sh -s -- --auth api-key

The installer does not write the key to local-stack.json or release metadata. During startup, the typed stack generator writes it only to the mode-0600 agent environment files under .runtime/ for Docker Compose. Keep the installation directory private. Use oblive auth status to verify that the configured variable is available; oblive auth login is only for local Codex mode.

Installer Options

For example, install without starting or editing a shell profile:

curl -fsSL https://oblive.dev/install.sh | \
  sh -s -- --channel latest --no-start --no-add-to-path

The installer updates .zshrc, .bash_profile on macOS Bash, .bashrc on Linux Bash, .config/fish/config.fish for Fish, or .profile as a portable fallback. Existing entries are not duplicated, and no profile is changed when the binary directory is already on PATH. When the current shell still needs refreshing, the installer prints the exact command to run.

Generated Files

The default installation creates:

• ~/.local/bin/oblive — the human operator CLI;
• ~/.oblive/local-stack.json — your mode-0600 configuration and generated secrets;
• ~/.oblive/local-stack.schema.json — editor completion and validation help;
• ~/.oblive/.runtime/ — generated Compose environment files; and
• release-pinned Compose files and metadata under ~/.oblive.

Edit only local-stack.json; generated environment files are outputs. The installer preserves an existing configuration during reinstall and update.

oblive config path
oblive config edit
oblive config check

First Start

If you used --no-start, start later with:

oblive start

Startup waits for PostgreSQL, Redis, and Garage, runs migrations once, then starts the backend, frontend, chat runtime, and configured worker replicas. The browser opens only after the stack is ready; use oblive start --no-open to suppress it.

Developing from Source

The portable installation needs no repository checkout. Contributors should use the separate Repository Guide and Local Stack and Migrations workflow.

Next

Learn everyday operations in Use the Oblive CLI. Then Verify and Maintain before you Onboard Your Business.