---
title: "Quickstart"
description: "Install OMS, start it, connect a model provider and sign in. Each step says what to do if it fails."
url: https://barestate.xyz/docs/quickstart
---

# Quickstart

> Install OMS, start it, connect a model provider and sign in. Each step says what to do if it fails.

This page takes you from nothing installed to your first request in OMS, which usually means one setup command and a couple of commands inside the app. Before you start, make sure you have Node 22.19.0 or newer and Git. OMS runs on macOS and Linux, and on Windows it runs under WSL 2.

### Install Surfpool and run the health check

```sh
npx @barestate/oms doctor --install
```

You only need to do this once. The command downloads Surfpool 1.7.0 for your platform, checks the download against a pinned SHA-256, copies the binary to `~/.oms/tools/surfpool-1.7.0/surfpool`, and then runs the doctor checks.

OMS uses this copy of Surfpool rather than one on your `PATH`, so a different version you already have installed does not get in the way. Builds exist for `darwin-arm64`, `darwin-x64` and `linux-x64`, and any other platform fails with `No Surfpool 1.7.0 build for ...`.

If the checksum does not match, nothing is installed. If a download fails, doctor reports it, and you can run the same command again.

### Start OMS

```sh
npx @barestate/oms
```

The first launch creates a starter workspace under `~/.oms/starter`. Opening OMS sends no model request, so nothing reaches a model until you connect one and ask for something.

### Connect a model provider

Inside OMS, run:

```text
/connect
/model
```

`/connect` offers an API key or, where the provider supports it, a subscription sign-in. `/model` then lists the models you can use. [Connect a model](https://barestate.xyz/docs/guides/connect-a-model) covers the details for each provider.

### Sign in to OMS (optional)

```text
/login
```

OMS shows a URL and a code and tries to open your browser, where you approve the code. You can skip this step, because the OMS account is used only for hosted web search.

### Type a request

Describe what you want in plain words. If you get stuck, `/help` lists the keyboard controls and every command, and `/quit` closes OMS after cleanup.

## Run from a source checkout

If you are working on OMS itself, you can run it from the repository instead of from npm:

```sh
npm ci --ignore-scripts
node packages/cli/src/bin.ts doctor --install
npm start
```

In a source checkout, OMS prefers `<repo>/.tmp/tools/surfpool` when that file exists.

## What doctor checks

Doctor runs the checks below. Only a blocking check that fails makes `oms doctor` exit with code 1, so warnings and info lines tell you something without stopping you.

| Check | Severity | What it needs |
|---|---|---|
| Node.js | Blocking | 22.19.0 or newer |
| Surfpool | Blocking | Runs and reports exactly 1.7.0 |
| Solana CLI | Blocking | `solana --version` works |
| Execution backend | Info | Reports host with Seatbelt, host without sandbox, or Docker |
| Docker | Optional in host mode, blocking in Docker mode | `docker info` works. In Docker mode the approved image must also be cached |
| Anchor | Info, blocking with `--programs` | `anchor --version` works |
| Surfnet RPC | Blocking, only with `--rpc` or `SURFNET_RPC_URL` | `getHealth` returns ok |
| Model access | Warning | One of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` or `DEEPSEEK_API_KEY` is set. A login is not checked |

## When something fails

### Doctor reports a blocking check

Fix the item it names and run `npx @barestate/oms doctor` again. The Surfpool check wants the exact pinned version, so a different Surfpool version does not pass.

### Doctor warns about model access

This is a warning, not a failure. Doctor only looks for the four API key variables in the table above and does not check a login, so if you plan to use `/connect` you can ignore it.

### Doctor says there is no sandbox

On Linux, and on macOS without `sandbox-exec`, host mode has no operating system sandbox. With no sandbox in place, OMS asks you to approve every shell command the model runs. See [Sandbox](https://barestate.xyz/docs/security/sandbox).

## Next

**[How a task runs](https://barestate.xyz/docs/concepts/how-a-task-runs)**
What happens after you type a request.

**[Work until a check passes](https://barestate.xyz/docs/guides/work-until-it-passes)**
Use `/goal` and `/verify`.