Repository navigation
Installation
Kabmo is published to npm and runs on Bun, not Node.
Bun only — the server imports
bun:sqliteandBun.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
ompbinary, soserverefuses to start when it is not onPATH(or set viaKABMO_OMP_BIN).MOCK=trueis the only mode that runs without a real omp install.Kabmo never installs omp itself —
servemeans "run the server", and a download into$HOMEis 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
probeOmpBinsearches~/.local/binand~/.bun/binas well asPATH, so either route is found without restarting anything. On a terminal,kabmo serveoffers thebun install -groute once and defaults to no; a piped,--jsonor--quietrun is never asked.
bun add -g @kabmo-labs/kabmo # puts the `kabmo` command on your PATH
kabmo serve # start the server on :3000An 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.
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 statusWithout
dist/clientthe server answers503with the exact command to run — never a bare500.
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 dateA 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.
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 |
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-readableExit 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.
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 entryThe 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/stopfor 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 detachedserve(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 againstlaunchctl print: the entry isstate = runningwith the CLI as its program. -
macOS registers
~/Library/LaunchAgents/dev.kabmo.tray.plist(RunAtLoad, noKeepAlive— 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\Runvalue throughreg, 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.NotifyIconon Windows, andyad/zenity--notificationon 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 colouris the shipped app icon, orange arm and all (the default);Monochromeis 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. -
--startupwithout--trayis a supported shape: the login-started server comes up without an icon.
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 3000is 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:LISTENcommand to identify it. -
localhostis two addresses, and the port is taken if either one is.Bun.servebinds only the family a name resolves to first ([::1]forlocalhost), so a check aimed at that family alone reported a free port while another instance held127.0.0.1— two servers answering "port 3000", and a browser landing on whichever one it resolved. Both127.0.0.1and::1are now probed (and both are asked over/api/health, which is whatstatus/stopuse 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 devhot reload is unaffected:--hotre-evaluates the entry inside the running process, and a port held by that process is recognized as its own. -
statusandlogsreport every live instance by default;--port <port>narrows them to one.stopacts on the instances the CLI started, andrestart/updateskip the rest:bun run devis 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.
-
stopreports 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 statusstill 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:statussaid "not running" whileserverefused 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/healthnames 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.
Using Kabmo
How it is built
- Architecture
- Runtime and toolchain
- App shell and layout
- Chat stream and tools
- omp engine and settings
- Plugins, skills and automation
- Desktop integration
- Workspace panels
- Providers
- Harnesses
- Tool panels
Shipping it
History