Getting started

Install & quickstart

Get the Orca daemon and its web UI running in under a minute. The same global package brings up both — there is no Docker, no compose file, no separate services to wire up.

Requirements

Node.js ≥ 22 — the daemon and the web UI both run on Node.
tmux — every agent runs in an isolated tmux session; this is mandatory.
An LLM provider + API key (only if you want autopilot planning via the relay backend; the agent backend carries its own model).

1. Install

npm install -g orcasynth

This makes the orca command available globally. Run with no argument for an interactive launcher menu — start/stop, first-run setup, update, open the web UI.

Prefer it non-interactive? The same actions are plain subcommands:

orca up         # start the daemon (:4400) + web UI (:4500) in the background
orca status     # show what's running
orca down       # stop everything
orca update     # update to the latest release from npm
orca install    # guided provisioning wizard (domain/TLS, ports, first admin)

2. First-run setup

On first run, orca walks you through a short setup:

Create the admin user (or pass ORCA_BOOTSTRAP_USER/ORCA_BOOTSTRAP_PASS from source).
Pick your LLM provider and paste an API key.
Choose a default model (you can add more in Settings later).

Your data — config, the SQLite database, and logs — lives in ~/.config/orca/ and survives every update.

3. Sign in

Open http://localhost:4500 and sign in with the admin account you just created. Configure models in Settings → Autopilot / Models, then create a task or engage an autopilot mission.

Run from source

For development, or to run without a global install. Requires the same prerequisites above.

# 1. Daemon (REST API on :4400)
git clone https://github.com/dragocz1995/orcasynth.git
cd orcasynth
npm install
npm run build
ORCA_BOOTSTRAP_USER=admin ORCA_BOOTSTRAP_PASS=changeme node dist/daemon/index.js

# 2. Web UI (on :4500)
cd web
npm install
npm run build
npm start -- -p 4500

Then open http://localhost:4500 and sign in. The CLI auto-starts the daemon if it isn't running:

node dist/cli/index.js ls          # list tasks
node dist/cli/index.js close <id>  # close a task

Provisioning wizard

If you're shipping to a server, orca install (run as root) is a guided provisioning wizard: systemd units, a reverse proxy, TLS via Let's Encrypt where applicable, and the first admin. It also supports an unattended mode:

sudo orca install --unattended
# see `orca install --help` for domain/TLS/port/engine flags

Verify it's up

$ orca status
  orcasynth v1.4.41

  daemon  ●  running  :4400  healthy
  web     ●  running  :4500  healthy  http://localhost:4500

Next up: read Concepts to learn how tasks, missions, and the overseer fit together.