installation

prerequisites#

before installing overlord, make sure you have:

  • node.js >= 20
  • redis (for the server — task queue and pub/sub)
  • git >= 2.20
  • an ai agent cli installed on worker machines (one or more of: claude, cursor, codex)

server setup#

install the overlord cli and server packages globally:

npm install -g @overlordai/cli @overlordai/server

run the interactive installation wizard:

overlord install

the wizard will:

  1. check that all prerequisites are met (node, redis, git)
  2. generate secrets (JWT_SECRET, WORKER_JWT_SECRET, ENCRYPTION_KEY)
  3. configure redis connection (default: redis://localhost:6379/0)
  4. initialize the sqlite database and run migrations
  5. create your admin account (username, password, git name, git email)

all configuration is written to ~/.overlord/.env.

start the server#

overlord start      # start services (systemd / launchd)
overlord status     # verify everything is running
overlord doctor     # run health check

the overlord start command automatically generates and registers system services (systemd on linux, launchd on macos).

add worker machines#

workers are the machines that actually run tasks. you need at least one worker to start using overlord.

1. generate a registration token#

in the web dashboard, go to admin → worker tokens → generate token. each token registers exactly one worker.

2. install worker on the target machine#

npm install -g @overlordai/cli @overlordai/worker

3. run the setup wizard#

overlord setup worker

the wizard will ask for your server url, the registration token, a machine name, and the number of concurrent task slots.

info

for detailed worker configuration, ssh keys, non-interactive mode, and troubleshooting, see the full worker setup guide.

4. verify connection#

once the worker starts, it will appear on the machines page in the web dashboard with status "online".

developer cli#

developers interact with overlord through the ov cli:

npm install -g @overlordai/developer-cli
 
ov setup                 # quick setup — configure server url + authenticate
ov task create -d "fix the login bug" -p PROJ
ov attach 42             # connect to a running task's terminal
info

the developer cli uses personal access tokens (pat) for authentication. generate one in the web dashboard under profile → access tokens.

verify installation#

after starting the server, open http://localhost:9000 in your browser and log in with the admin credentials you created during installation. check the machines page to verify workers are connected.

next steps#

worker setup