Appearance

Install the runtime ​

Install the Kadmo runtime on your computer, start it, 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 ​

bash
npm install -g @kadmo/cli

The package is @kadmo/cli; it puts the kadmo command on your path. To run it without a global install, use npx @kadmo/cli in place of kadmo in every command on this site.

Start it ​

bash
kadmo serve

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

text
  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>/

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).

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.

To use the runtime from Claude Code, Cursor or another MCP client you do not need kadmo serve at all: the client starts kadmo mcp itself. See The MCP server.

Check that it runs ​

bash
curl http://localhost:9876/health

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

json
{
  "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.

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:

bash
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:

yaml
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 kadmo serve running and the extension connected:

bash
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:

SettingWhat it isDefaultOverridden by
app_urlThe Kadmo app: jobs, uploads, the session stream, kadmo publish and kadmo loginhttps://app.kadmo.aiKADMO_APP_URL, then PORTAL_URL
catalogue_urlThe public pack catalogue that kadmo install <domain> and kadmo search askhttps://app.kadmo.aiKADMO_CATALOGUE_URL, then PORTAL_URL

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

VariablePurpose
KADMO_AGENT_TOKENThe bearer for the REST API beyond a loopback caller of a loopback bind, and always for HTTP MCP; required for a wide bind
KADMO_HOSTBind address, default 127.0.0.1
KADMO_APP_URL, KADMO_CATALOGUE_URLOverride app_url and catalogue_url
OPENAI_API_KEY, ANTHROPIC_API_KEYThe provider key for a workflow's llm.* steps
DISPLAYDesktop screenshots on Linux

The runtime also reads a .env file in the directory you start it from. 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.

PathHolds
settings.jsonSettings: 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.jsonWhat 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.mdRole guides, targets and the persona the dashboard's Settings page edits
auth.jsonThe personal API token kadmo login stores (mode 600)
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 ​

bash
npm install -g @kadmo/cli@latest

Restart kadmo serve, and restart your MCP client so it starts the new kadmo mcp.

Remove ​

bash
npm uninstall -g @kadmo/cli

This leaves ~/.kadmo in place. Delete that directory too to remove your packs, workflows, run logs and the stored token.

On agents ​

Every Kadmo agent runs the runtime as a service; Kadmo installs the package on the agent's machine at a pinned version, so nothing on this page is needed for an agent.

Next steps ​

© Kadmo GmbH