Installation
OKR.ai is a Node.js app on npm as okr-ai. One command installs and starts it.
Requirements
- Node.js 22.13 or newer. The built-in database uses
node:sqlite, which needs this version. - macOS, Linux or Windows. Any machine that runs Node.js works, from a laptop to a container.
$ node --version
Run with npx
The quickest way to try OKR.ai. It downloads the latest release and starts it:
$ npx okr-ai@latest
Open http://localhost:3000 and enter your name and role. There’s no sign-in: a new install is just you, and only this computer can open it. See Create your workspace.
Data goes to ./data in the folder you ran the command from, and a secret key is made for you in data/.secret-key. Run every okr-ai command from that folder, or pass --dir <folder>.
Commands
| Command | What it does |
|---|---|
npx okr-ai | Starts the app on localhost:3000. If it’s already running, says so. |
npx okr-ai status | Solo or team, what’s running and what’s left to do. --json for scripts and AI assistants. |
npx okr-ai connect <assistant> | Connects Claude Code, Claude Desktop, Codex, Cursor or VS Code. See AI assistants (MCP). |
npx okr-ai join <code> | Joins the team whose join code you were given. OKR.ai must be running. |
npx okr-ai leave | Takes this computer off the team. Your earlier solo data comes back. |
npx okr-ai --help | Every option: --port, --host, --dir, --url. |
Install globally
For a machine you’ll keep running OKR.ai on, install the command once:
$ npm install -g okr-ai $ mkdir -p ~/okr-ai && cd ~/okr-ai $ okr-ai
Settings are read from a .env file in the current folder and from environment variables. See Configuration.
Change the port
$ npx okr-ai --port 4000
Pass the same --port to status, connect and join. OKR.ai listens on this machine only (127.0.0.1). To serve a team from one server, see Self-hosting in production.
Optional: a local Postgres
The built-in SQLite database is enough to get started. To try the PostgreSQL option locally with Docker:
$ docker run -d --name okrai-pg -p 5432:5432 -e POSTGRES_USER=okrai -e POSTGRES_PASSWORD=okrai -e POSTGRES_DB=okrai postgres:16 # postgres://okrai:okrai@localhost:5432/okrai
Optional: MySQL driver
MySQL, MariaDB and PlanetScale use the mysql2 driver, which is left out of the default install to keep the dependency count low. Install it only if you need it:
$ npm i mysql2
Updating
With npx, @latest always fetches the newest release. With a global install, run npm install -g okr-ai@latest. OKR.ai creates any missing tables on start-up with idempotent CREATE … IF NOT EXISTS statements.
Uninstalling
Run npm uninstall -g okr-ai and delete the data folder. If you connected an external database, drop the tables that start with okr_.