Skip to main content
The setup wizard takes a fresh repository checkout to a working first session. It checks system requirements before installing dependencies or starting containers, then explains each resource it creates.

​
Prerequisites

Install these system packages before starting: Docker Compose is optional because OAO can manage its PostgreSQL container with the Docker CLI. The wizard also checks that the repository is complete, the workspace is writable, enough disk space is available, and ports 3000, 5432, 8080, and 8788 are free or already owned by a healthy OAO stack.
The wizard cannot install or start system software on your behalf. Failed checks include a platform-appropriate repair command, then setup stops before changing the repository or Docker state.

​
Check the machine

Clone the repository, enter it, and run the dependency-free doctor:
Use machine-readable output in CI or support scripts:
Warnings describe optional or setup-managed items. Resolve every failed system check before continuing.

​
Run guided setup

The wizard:
  1. Repeats the non-mutating system checks.
  2. Installs the exact dependencies from pnpm-lock.yaml and obtains the pinned PostgreSQL image when it is not cached.
  3. Creates .env when needed and generates a 32-byte credential encryption key.
  4. Starts PostgreSQL, applies migrations, seeds the local development tenant, and waits for the API, runtime worker, and console.
  5. Shows an arrow-key selector for OpenRouter, OpenAI, Anthropic, or xAI, then reads the API key with terminal echo disabled.
  6. Validates the connection and opens a live model search box. Type any part of the model name or provider ID, use the arrow keys to move through matching results, and press Enter to create the versioned model preset and a sandbox-disabled oao-starter agent.
  7. Starts a durable session, waits for its first run to settle, and prints the assistant response and console URL.
Provider API keys are written only through OAO’s encrypted, write-only credential API. They are not stored in shell history, .env, logs, or .oao/setup-state.json. The local state file contains only non-secret resource identifiers and is created with owner-only permissions.
Guided setup uses development authentication, which trusts requests from the local machine. Do not expose this profile to an untrusted network or use it as a production authentication mode.
Leave the terminal open while using OAO. Press Ctrl+C to stop processes started by the wizard. PostgreSQL data remains in its named Docker volume.

​
Resume or inspect setup

Setup is safe to run again:
The wizard discovers or reuses the provider connection, model preset, starter agent, and recorded session instead of creating duplicates. If validation of an existing connection fails, it asks for a replacement key and rotates that write-only credential. Inspect the stack or open the console at any time:
The console is available at http://127.0.0.1:8080.

​
Reset and start over

First stop the terminal running pnpm oao setup or pnpm dev:local with Ctrl+C. Then run:
The command refuses to continue while an OAO API, runtime worker, or console is still active. It shows the exact deletion scope and requires you to type RESET. A successful reset permanently removes:
  • the oao-postgres-data volume, including every local agent, session, run, provider connection, and encrypted credential;
  • .env, including local authentication and port settings; and
  • .oao, including setup identifiers and wizard logs.
Workspace dependencies and cached Docker images remain available. Run pnpm oao doctor followed by pnpm oao setup to create a fresh environment. For intentional non-interactive automation, pnpm oao reset --yes skips only the confirmation prompt; it does not bypass the running-service safety check. New setups also record the active Docker context, and reset refuses to delete a same-named volume after the user switches to a different context.
Reset is irreversible unless the Docker volume is backed up separately. Do not use it as a troubleshooting step when you need to preserve local agents, transcripts, or provider configuration.

​
Troubleshooting

  • Docker daemon unreachable: start Docker Desktop, Colima, or another Docker-compatible daemon, then rerun pnpm oao doctor.
  • Wrong Node or pnpm version: install a supported Node release and activate pnpm 10.27.0 with Corepack.
  • Port already in use: stop the conflicting process. A healthy existing OAO stack is detected and reused.
  • Invalid encryption key: preserve any key that protects existing credentials. For a new empty environment, remove the invalid local value and let setup generate one.
  • Provider validation fails: confirm the API key can list models, then rerun setup and rotate the credential when prompted.
For manual process control, authentication configuration, and service-level health checks, continue to Local development.