Installation

OKR.ai is a Node.js app. Install it from npm to run it, or clone the repository to change 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. Data goes to ./data/okrai.db in the folder you ran the command from.

#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

$ PORT=4000 npx okr-ai

If you put OKR.ai behind a different public URL, also set OKRAI_URL so sign-in links and OIDC redirects point to the right place.

#Optional: a local Postgres

The built-in SQLite database is enough to get started. To try the PostgreSQL option locally, the repository includes a Docker Compose file:

$ docker compose up -d
# 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. From source, git pull then npm install. 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_.