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.
1

Install Surfpool and run the health check

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.
2

Start 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.
3

Connect a model provider

Inside OMS, run:
/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 covers the details for each provider.
4

Sign in to OMS (optional)

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.
5

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:
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.

When something fails

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.
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.
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.

Next

How a task runs

What happens after you type a request.

Work until a check passes

Use /goal and /verify.