Install the runtime

Install the Kadmo runtime on your computer, run it as a login service, and get your first workflow.

Requirements

• Node.js 22 or newer, with npm.
• Chrome with the Kadmo extension for the browser tools. Workflows, run logs and packs work without it.

Install

npm install -g @kadmo/cli

The package is @kadmo/cli; it puts the kadmo command on your path. To run a command without a global install, use npx @kadmo/cli in place of kadmo; the login service below is the exception, because it needs the global install.

Install it as a login service

kadmo service install

This installs the runtime (kadmo serve) as a login service for you only, without administrator or root rights, starts it now and waits until it answers. From then on it starts whenever you log in, and comes back by itself when its process stops: on Linux and macOS within about 10 seconds, on Windows within seconds (the task itself also restarts on failure, every minute).

The runtime runs once per user. Every MCP client's kadmo mcp relays to it (see The MCP server), and the extension connects to it, so all of them share the one browser, the dashboard and the workflows.

Check it:

kadmo service status

It prints the service's state (installed, running, its pid, its file and where its logs are), whether the runtime that answers was started by the service or by hand, and, on a computer that is an agent, the last dependency report. It exits 0 when the service runs the runtime, and 1 otherwise. All four kadmo service commands are on The kadmo commands.

Your computer	The service	Its file	Its logs	Start it by hand
Linux	systemd user unit kadmo.service	~/.config/systemd/user/kadmo.service (under $XDG_CONFIG_HOME when that is set)	journalctl --user -u kadmo	systemctl --user start kadmo
macOS	LaunchAgent ai.kadmo.runtime	~/Library/LaunchAgents/ai.kadmo.runtime.plist	~/.kadmo/logs/service.log	launchctl kickstart gui/$(id -u)/ai.kadmo.runtime
Windows	logon task Kadmo runtime, for your user, running hidden	%USERPROFILE%\.kadmo\service\kadmo-runtime.xml and kadmo-runtime.vbs	%USERPROFILE%\.kadmo\logs\service.log	schtasks /Run /TN "Kadmo runtime"

• Linux needs a desktop login session, because a user unit runs on your user's systemd. On a machine without one (a server you reach over SSH), run loginctl enable-linger $USER first.
• The service's environment. The runtime starts in ~/.kadmo, so the .env it reads is ~/.kadmo/.env, not one in a project folder (see Settings). It keeps the PATH of the shell you ran kadmo service install in, so claude, node and npm resolve under it.
• A runtime you started by hand (kadmo serve in a terminal) holds the runtime's place for your user. kadmo service install names its pid and stops; stop it and run the command again, or run kadmo service install --replace, which stops it first.
• Not under npx. Run from an npx cache, kadmo service install refuses: install the package globally first (above), so the service starts a path that stays.

Try it once in a terminal

To try the runtime without the service, run it in a terminal:

kadmo serve

Bare kadmo does the same. The runtime prints its addresses and keeps running until you stop it with Ctrl+C:

  Kadmo

  Config: /home/you/.kadmo
[kadmo] HTTP /mcp needs KADMO_AGENT_TOKEN; use kadmo mcp over stdio.

Kadmo server started on http://localhost:9876
  - Dashboard:  http://localhost:9876
  - WebSocket:  ws://localhost:9876/ws
  - MCP:        http://localhost:9876/mcp
  - API:        http://localhost:9876/api
  - Preview:    http://localhost:9876/api/preview/<devPort>/
  - Sessions:   /home/you/.kadmo/run/kadmo.sock

Press Ctrl+C to stop

The HTTP /mcp needs KADMO_AGENT_TOKEN line is expected on your own computer: MCP clients use kadmo mcp over stdio (see The MCP server). While the service runs, kadmo serve finds the runtime already running for your user, names it and exits 1.

It binds 127.0.0.1 only, so nothing outside your computer can reach it. --port changes the port (but the extension always connects to 9876, see The Kadmo extension), and --host widens the bind, which then requires KADMO_AGENT_TOKEN. All options are on The kadmo commands.

Check that it runs

curl http://localhost:9876/health

The answer starts like this (it carries more fields about the machine):

{
  "status": "ok",
  "version": "0.1.0",
  "desktop_connected": true,
  "browser_connected": false,
  "workflows_running": 0
}

browser_connected turns true once the Kadmo extension is installed and has attached a tab. kadmo status prints the same in short form, and kadmo doctor says what stands between your MCP clients and the browser, each line with its fix (kadmo doctor).

The dashboard

Open http://localhost:9876 in your browser, or click Open Dashboard in the extension's popup. The dashboard shows the installed packs, the workflows, the run logs and the settings: see The dashboard.

First run

The package ships no packs, so a fresh runtime has no workflows. Get one of two ways:

Install a pack. Search the public catalogue and your registries, then install a pack by its domain:

kadmo search
kadmo install <domain>
kadmo list

kadmo list prints the workflows the runtime now has; run one from the dashboard or with kadmo run <workflow>. Where else packs come from (a registry, a git repository, a local directory) is on kadmo install.

Write a workflow. A YAML file in ~/.kadmo/actions/ is a workflow of your own. This one opens a page in the driven tab and reads its heading:

id: read_heading
title: "Read a page's heading"
params:
  url: string
steps:
  - type: browser.navigate
    url: "{{url}}"
  - type: browser.extract
    selector: "h1"
    as: heading

Save it as ~/.kadmo/actions/read_heading.yaml, then, with the runtime running and the extension connected:

kadmo run read_heading --param url=https://example.com

kadmo run starts the run and returns its run id; the result is in the dashboard's run logs. The workflow language is on Workflows and Step types.

Settings

The runtime reads ~/.kadmo/settings.json; the dashboard's Settings page edits it. Two settings name the Kadmo services the runtime talks to:

Setting	What it is	Default	Overridden by
app_url	The Kadmo app: jobs, uploads, the session stream, kadmo publish and kadmo login	https://app.kadmo.ai	KADMO_APP_URL, then PORTAL_URL
catalogue_url	The public pack catalogue that kadmo install <domain> and kadmo search ask	https://app.kadmo.ai	KADMO_CATALOGUE_URL, then PORTAL_URL

No environment variable is required on your own computer. The ones the runtime reads:

Variable	Purpose
KADMO_AGENT_TOKEN	An agent's bearer for the REST API and HTTP MCP, accepted beside the run token in ~/.kadmo/run/token; required for a wide bind. On a computer of yours it makes the runtime report to that agent (below)
KADMO_AGENT_NAME	The agent's name for its heartbeat, on a computer of yours that is an agent
KADMO_HOST	Bind address, default 127.0.0.1
KADMO_APP_URL, KADMO_CATALOGUE_URL	Override app_url and catalogue_url
OPENAI_API_KEY, ANTHROPIC_API_KEY	The provider key for a workflow's llm.* steps
DISPLAY	Desktop screenshots on Linux. The login service keeps the DISPLAY (and WAYLAND_DISPLAY) of the shell you ran kadmo service install in; run it again from your desktop session when that changes

The runtime also reads a .env file in the directory it starts in. Under the login service that is ~/.kadmo, so put the variables the service should see in ~/.kadmo/.env and run kadmo service restart; a .env in a project folder is read only by a kadmo serve you start in that folder. The agent token is also read from ~/.agent-env. The variables an agent's machine carries (PORTAL_URL, AGENT_TOKEN, AGENT_NAME and the rest) are set by Kadmo when it creates the agent.

The ~/.kadmo directory

Every start creates skills/, actions/ and workflows/; the rest appears the first time something writes it.

Path	Holds
.env	The variables the login service's runtime reads (see Settings)
settings.json	Settings: app_url, catalogue_url, the registries you added, the LLM provider, the dashboard's shortcuts and contexts
skills/<domain>/	One installed pack per domain
.installed/skill-packs.json	What is installed, with each pack's layer and version
actions/	Your own workflows (YAML)
workflows/	More workflows of your own (YAML); like actions/, they win over every pack
registries/<name>/	The clones of git registries
plugins/<name>/	Installed plugins
run_logs/	One log per workflow run
roles/, targets/, persona.md	Role guides, targets and the persona the dashboard's Settings page edits
auth.json	The personal API token kadmo login stores (mode 600)
run/	On macOS and Linux, the socket kadmo.sock every kadmo mcp relays through (on Windows a named pipe); on every system the run token token, which the kadmo commands and the relays show the runtime (readable only by you)
logs/service.log	The login service's log, on macOS and Windows
service/	The logon task's two files, on Windows
ops/	The agent ops version and ETag, on an agent's machine

Outside ~/.kadmo, the runtime writes to one file: once the agents pack is installed, it keeps a managed block in ~/.claude/CLAUDE.md up to date, at every start.

Update

npm install -g @kadmo/cli@latest && kadmo service install

Running kadmo service install again rewrites the service for the new version and restarts the runtime through it. Your MCP clients need no restart: each kadmo mcp reconnects to the new runtime and lists its tools again. Until a client restarts, its kadmo mcp is the old version; it still relays, and the runtime's status reports the version mismatch.

Run kadmo service install again too after a Node.js upgrade that moves the node binary, because the service starts the exact node it was installed with; kadmo service status says when that is needed. To restart the runtime without changing the service, for example after you edit ~/.kadmo/.env:

kadmo service restart

Remove

kadmo service uninstall
npm uninstall -g @kadmo/cli

kadmo service uninstall stops the runtime and removes the service and its files. Neither command touches ~/.kadmo: delete that directory too to remove your packs, workflows, run logs, settings and the stored token.

On agents

Every Kadmo agent VM runs the runtime as its own system unit, kadmo.service; Kadmo installs the package on the agent's machine at a pinned version, and the agent's install and its Self Update job manage the unit, which restarts by itself. Nothing on this page is needed for an agent VM. There, kadmo service status reports kadmo.service read-only (its logs: journalctl -u kadmo), and kadmo service install, restart and uninstall refuse to change it.

A computer of yours as an agent

When ~/.kadmo/.env holds an agent's KADMO_AGENT_TOKEN, the runtime the login service started reports itself to the Kadmo app as that agent's Kadmo runtime dependency (the item kadmo-runtime), with its version, at start and every 10 minutes. The agent's page then tracks it like an agent VM's: its row under Tools & dependencies, and Update pending when the version differs from the one the agent should run. With KADMO_AGENT_NAME set too, the runtime also sends the agent's heartbeat with its dependency versions. PORTAL_URL names the app when it is not https://app.kadmo.ai. A runtime you start by hand with kadmo serve reports nothing, so trying the runtime once never speaks for the agent.

KADMO_AGENT_TOKEN=your-agent-token
KADMO_AGENT_NAME=your-agent-name

Run kadmo service restart after you change the file; kadmo service status shows when the last report was sent, or why it failed.

Next steps

• Install the Kadmo extension — let the runtime drive Chrome
• Register the MCP server — use the runtime from Claude Code, Cursor and other clients
• The kadmo commands — every command and flag
• Troubleshooting — when something does not start