> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oao.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Guided quickstart
> Check your machine, start OAO, and create your first agent and session from the terminal.
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:
| Requirement | Minimum | Why it is needed |
| - | - | - |
| Node.js | 22.19.0 | Runs the workspace and CLI |
| pnpm | 10.27.0 | Installs the pinned workspace dependencies |
| Docker | Current supported release | Runs PostgreSQL 17 |
| Docker daemon | Running and reachable | Starts and inspects containers |
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:
```bash theme={null}
git clone https://github.com/vectrix-ai/oao.git
cd oao
pnpm oao doctor
```
Use machine-readable output in CI or support scripts:
```bash theme={null}
pnpm oao doctor --json
```
Warnings describe optional or setup-managed items. Resolve every failed system
check before continuing.
## Run guided setup
```bash theme={null}
pnpm oao 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:
```bash theme={null}
pnpm oao setup
```
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:
```bash theme={null}
pnpm oao status
pnpm oao open
```
The console is available at [http://127.0.0.1:8080](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:
```bash theme={null}
pnpm oao reset
```
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](/getting-started/local-development).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.