Skip to content

Installation

Wijanarko Putra Rajeb edited this page Nov 20, 2026 · 5 revisions

Installation, CLI and running instances

Kabmo is published to npm and runs on Bun, not Node.

Bun only — the server imports bun:sqlite and Bun.YAML, neither of which Node can load. Bun 1.4 or newer is required.

omp required — every live capability (agent sessions, omp config, session state, updates) shells out to the omp binary, so serve refuses to start when it is not on PATH (or set via KABMO_OMP_BIN). MOCK=true is the only mode that runs without a real omp install.

Kabmo never installs omp itself — serve means "run the server", and a download into $HOME is not part of that. Install it first, either way:

bun install -g @oh-my-pi/pi-coding-agent   # from source, with the Bun this needs anyway
curl -fsSL https://omp.sh/install | sh     # omp's own installer: sha256-verified prebuilt binary
omp --version                              # what `kabmo doctor` will report

probeOmpBin searches ~/.local/bin and ~/.bun/bin as well as PATH, so either route is found without restarting anything. On a terminal, kabmo serve offers the bun install -g route once and defaults to no; a piped, --json or --quiet run is never asked.

bun add -g @kabmo-labs/kabmo   # puts the `kabmo` command on your PATH
kabmo serve                    # start the server on :3000

An install that predates the rename keeps its state: the first boot moves ~/.ompchamber to ~/.kabmo (database, login, sessions and marketplace), and the OMPCHAMBER_* environment names are still read as fallbacks.

The published tarball carries the source, the CLI and the prebuilt client bundle, so there is no build step after install. npm install -g @kabmo-labs/kabmo works too — the kabmo bin is a Bun script, so Bun still has to be on PATH.

From source

git clone https://github.com/kabmo-labs/kabmo.git
cd kabmo
bun install
bun run build                        # dist/client — the only build artifact

bun run start                        # NODE_ENV=production bun run src/server/index.ts
bun link                             # then: kabmo status

Without dist/client the server answers 503 with the exact command to run — never a bare 500.

Updating

kabmo update --check        # report only: current version, latest release
kabmo update                # install it, then restart a running instance
kabmo update --force        # reinstall even when already up to date

A bun global install is refreshed with bun add -g @kabmo-labs/kabmo@<version>; a git checkout is fast-forwarded to the release tag and rebuilt. Uncommitted work is never merged over (the update asks you to commit or stash first), and an install owned by another package manager is left alone and told which command to run.

A server Kabmo did not start is never restarted: bun run dev, bun run start, a manual bun src/server/index.ts and instances owned by a supervisor (systemd, pm2, a container) all record themselves as direct, so the update leaves them running and says so. --no-restart turns the restart off entirely. The console's About → Updates runs the same install, restarts the instance serving that console, and reloads the page once the replacement answers on the same port.

CLI

kabmo [COMMAND] [OPTIONS] — serve is the default command.

Command Purpose
serve Start the web server (daemon by default)
update Install the latest version from npm, then restart the instance it started
stop Stop the instances the CLI started — --port/--all to stop any
restart Stop, then start again — leaving servers started from source alone
status Report whether an instance is running, and whether omp resolves
doctor Diagnose this install read-only: omp binary and version, latest release, Bun, data paths, install method
logs Print or follow the server log
plugin Build, type, scaffold or list panel plugins
Option Purpose
-p, --port <port> Web server port (default 3000); scopes status/stop/restart/logs
--host <address> (--hostname) Bind address (default 127.0.0.1)
--lan Bind to 0.0.0.0 for LAN access (warns when the traffic is unencrypted)
--tls Serve HTTPS from a self-signed certificate, generated once into ~/.kabmo/tls/
--tray Show a menu-bar/notification-area icon for this server
--startup Start the server at login (and show the tray icon now)
--no-startup Remove the login entry
--ui-password [value] Require a password for the browser UI; generates one when the value is omitted
--no-ui-password Ignore KABMO_UI_PASSWORD for this start
--prod Accepted for compatibility — production is the default
--dev Run the dev server from source (HMR, unminified) instead
--foreground (--no-daemon) Run in the foreground (no daemon)
--all Apply the command to every running instance
-c, --check Report whether a newer release exists without installing it
--force Reinstall even when already up to date
--no-restart Do not restart a running instance after updating
-f, --follow / -n, --lines <count> Tail the log, optionally from a line count
--json / -q, --quiet Machine-readable output / suppress non-essential output

Diagnosing an install

kabmo doctor is read-only: it resolves paths, asks omp --version, reads one npm document and lists live instances — it never opens the database (opening creates the file), spawns a server or writes a login entry.

kabmo doctor            # human table
kabmo doctor --json     # the same facts, machine-readable

Exit code 1 means Kabmo genuinely cannot run: no resolvable omp, or one whose version cannot be read. A registry outage (latest: null) and an unwritten db.sqlite are notes, not failures — an air-gapped install is still a working install, and MOCK=true is healthy without a binary at all.

The install commands themselves live in one module (src/server/lib/omp/core/install-hint.ts) and every surface that prints a remedy reads it — the serve refusal, --help, status and doctor. Four copies drifted into three different answers once; a suite pins both routes now.

Tray icon and start at login

kabmo serve --tray puts a Kabmo icon in the menu bar (macOS) or the notification area (Windows, Linux). --startup additionally registers the server to start at every login, and --no-startup removes that registration:

kabmo serve --tray          # start the server with a tray icon
kabmo serve --startup       # also start at every login
kabmo serve --no-startup    # remove the login entry

The icon's menu reflects the server as it is right now — rebuilt on every open: Open Console, Open Logs, Start at Login / Disable Start at Login, Quit Kabmo.

  • The tray is a child of the server. It exits when the server does (it watches its parent), so a killed or crashed server leaves no orphan icon, and Quit Kabmo signals the server — the icon and the console end together. There is no pid file, no status/stop for the icon, and nothing to keep in sync: the process tree is the registration.
  • The login entry runs serve --foreground. launchd reaps a job's whole process tree when the job's program exits, so an entry that ran a detached serve (which returns once the health check passes) produced no server at all. In the foreground the CLI is the long-lived job, the server is its child, and the tray is the server's child. Verified against launchctl print: the entry is state = running with the CLI as its program.
  • macOS registers ~/Library/LaunchAgents/dev.kabmo.tray.plist (RunAtLoad, no KeepAlive — a server stopped on purpose stays stopped). Linux writes $XDG_CONFIG_HOME/autostart/kabmo-tray.desktop, which every freedesktop session reads. Windows sets the HKCU …\CurrentVersion\Run value through reg, so registering never needs elevation.
  • What draws the icon is the platform's own tray API: an AppKit status item on macOS (via osascript -l JavaScript), System.Windows.Forms.NotifyIcon on Windows, and yad/zenity --notification on Linux. Only Linux can lack a client — the icon is then skipped with the package to install in the log, and the server keeps running.
  • The icon has two styles, chosen in Settings → Appearance → Shell → Tray icon. Full colour is the shipped app icon, orange arm and all (the default); Monochrome is a greyscale conversion: the green plate and the cream strokes swap luminance with the theme, and the orange arm becomes the middle grey. The greys are drawn as-is on every platform, including macOS. A running tray is restarted when the choice (or the theme that picks the plate) changes, so the icon updates without a server restart.
  • --startup without --tray is a supported shape: the login-started server comes up without an icon.

Ports and multiple instances

One port is served by exactly one process, and bun run dev, kabmo serve and the production server all default to 3000. A starting instance never stops another one — if the port is taken by Kabmo, the newcomer reports who holds it and exits non-zero so you can pick another port:

kabmo serve --port 3001        # CLI flag
KABMO_PORT=3001 kabmo serve
PORT=3001 bun run dev              # or: PORT=3001 bun run start
  • Nothing is ever signalled to free a port; kabmo stop --port 3000 is the deliberate way.
  • A process that is not Kabmo is never signalled either: the server names the port and prints the lsof -nP -iTCP:<port> -sTCP:LISTEN command to identify it.
  • localhost is two addresses, and the port is taken if either one is. Bun.serve binds only the family a name resolves to first ([::1] for localhost), so a check aimed at that family alone reported a free port while another instance held 127.0.0.1 — two servers answering "port 3000", and a browser landing on whichever one it resolved. Both 127.0.0.1 and ::1 are now probed (and both are asked over /api/health, which is what status/stop use to find a live instance), and the refusal names the address that is held. A literal address (--host 0.0.0.0, 127.0.0.1) is one address and is probed as exactly that.
  • bun run dev hot reload is unaffected: --hot re-evaluates the entry inside the running process, and a port held by that process is recognized as its own.
  • status and logs report every live instance by default; --port <port> narrows them to one. stop acts on the instances the CLI started, and restart/update skip the rest: bun run dev is a supervisor whose only job is to mirror the script under it, so stopping that server exits the dev loop with it. Name the instance — kabmo stop --port <port>, or --all — to end one anyway.

The server writes ~/.kabmo/run/<port>.json (pid, host, mode, launchMode, startedAt) once it owns the port, which is how status/stop/logs also see servers started by bun run dev or --foreground. launchMode is derived from the process's argv, never from an environment variable — env is inherited, so a bun run dev started inside a Kabmo shell would otherwise be replaced by an update. Records left by a killed server are pruned once their PID stops answering.

  • stop reports what actually happened. The record is dropped only once the process is gone, so a stop that could not end the server keeps it — kabmo status still finds the instance, the message says so, and the command exits non-zero. Deleting the record over a live process was how a failed stop turned into a deadlock: status said "not running" while serve refused the port.
  • A PID whose identity cannot be read (Windows cannot read another process's command line, so every PID there reads back as unverified) is resolved through the port instead: /api/health names the instance serving it. Only when the port names a different PID — a recycled PID, a foreign listener — is the record treated as stale and cleared without signalling anything.

Implementation detail for the tray, the login entry and the OS document handlers: Desktop integration.

Clone this wiki locally