Self-hosting an agent

You can attach a machine you run yourself to Kadmo as one of your agents: a server, a VM in any cloud, or a box in your office. The app gives you a one-line installer with a single-use token; you run it on a fresh Ubuntu 24.04 machine, it installs the desktop, Chrome, the coding app and the agent runtime, and the machine checks in to the app as that agent. This page covers the requirements, the installer, how the agent appears in the app, and how to update and remove it.

In this release

The app reaches agents over Kadmo's private network. A machine outside that network installs, checks in and shows its status, but the app cannot reach it: it takes no jobs, and its live desktop does not open. Agents that work today are hosted by Kadmo or run in an AWS agent subnet peered with Kadmo. If you need agents on your own hardware, book a call.

How attaching works

 The app (Agent Fleet)                    Your machine (Ubuntu 24.04)
 ─────────────────────                    ───────────────────────────
 Reveal Agent token ── single-use ──▶     curl … /install.sh | sudo … bash
                       token                · desktop, Chrome, coding app
                                            · the agent runtime service
                                            · the Kadmo agent ops + 5-minute sync
        ▲                                          │
        │                                  first check-in
        └──── the agent reports Online ◀── the token is exchanged for the
                                           agent's own permanent token

The token in the command is a single-use bootstrap token that expires after 60 minutes. At the first check-in the app exchanges it for the agent's permanent token, which stays on the machine; the bootstrap token is never needed again.

Requirements

Requirement	Details
Operating system	Ubuntu 24.04, ideally a fresh install
Access	root, or a user who can run sudo
Network	Outbound HTTPS to app.kadmo.ai (check-ins, the agent ops) and to github.com (the installer downloads the agent runtime from there)
A dedicated machine	The installer sets up a desktop session, Chrome and background services, and creates the agent user. Do not run it on a workstation you use for other things
Size	2 vCPU, 8 GB memory and 40 GB disk is a comfortable baseline for one agent, the same as a Medium cloud agent
In the app	The admin role, and the agent you want this machine to be (the token belongs to one agent)

Step 1: Get the installer command

1. Open Agent Fleet and click the agent's name to open its page.
2. In the Agent token section ("Connect a self-hosted agent"), click Reveal Agent token.
3. The dialog shows the Agent token and the Install command with the token already filled in, and how long the token has left. Click Copy.

The same command is behind Danger zone → Re-install ("Re-install on another VM"), which you use to move an agent to a new machine. A token that expires before you use it is simply replaced: reveal a new one.

Step 2: Run the installer

On your machine, paste the command. It has this shape:

curl -sSf https://app.kadmo.ai/install.sh | sudo \
  AGENT_TOKEN=your-single-use-token \
  AGENT_NAME=your-agent-name \
  AGENT_ROLE=se \
  PORTAL_URL=https://app.kadmo.ai bash

Pass the token on the command line as shown; do not write it into a file or a machine image. The installer prints every step with a timestamp. A full install takes several minutes.

Installer variables

Variable	Required	Default	Meaning
AGENT_TOKEN	yes	none	The single-use token from Step 1
AGENT_NAME	yes	none	The agent's name; keep the one the app filled in
PORTAL_URL	yes	none	The app's address, https://app.kadmo.ai. It has no default, so an agent never enrols anywhere else
AGENT_ROLE	no	se	The agent's starting role: se, qa or sd
AGENT_PASSWORD	no	random	The password of the agent user, used for remote-desktop logins
AGENT_RUNNER	no	the standard setup	Advanced: selects another runtime variant. Leave it unset

What the installer does

1. Checks that it runs as root and that PORTAL_URL, AGENT_TOKEN and AGENT_NAME are set.
2. Installs curl and tar if the machine lacks them.
3. Downloads the agent runtime installer from GitHub and runs it. That installs the desktop session (Xvfb, XFCE, x11vnc), Google Chrome, Claude Code and the agent runtime, which runs as the sidebutton.service systemd unit.
4. Checks in to the app with the token. The agent takes the token's place on the fleet, and the app writes the agent's own settings to the machine.
5. Installs the Kadmo agent ops (the built-in roles and the workflows playbooks run) with the agent's own token, and starts the kadmo-ops-sync.timer, which keeps them current every 5 minutes and adds the public skill-pack library as a registry.

The installer is safe to run again. On a machine it already finished, it only checks the desktop, Chrome and agent runtime services and sets up the agent ops again, then exits with "already installed". To start over, use a fresh machine.

Step 3: See the agent in the app

On Agent Fleet, the agent's card reports Online once its first check-in arrives and keeps it while the agent checks in at least every 5 minutes. Its page shows BYO-VM where a cloud agent shows its provider. A self-hosted agent is not put on the 15-minute setup hold that new cloud agents get.

On the machine, these show what runs:

systemctl status sidebutton.service          # the agent runtime
systemctl list-timers kadmo-ops-sync.timer   # the 5-minute agent ops sync
journalctl -u kadmo-ops-sync                 # what the last syncs did

If the agent runs Claude Code on a subscription app, sign it in once on its desktop: see Use your Claude subscription.

Keeping it up to date

What	How
Agent ops	kadmo-ops-sync checks the app every 5 minutes and installs a new version when there is one
Skill packs	The public library and your account's packs are pulled every 5 minutes
Agent runtime	Run the Self Update job on the agent (Run Job → Self Update). It upgrades the runtime and its helper scripts, and runs the ops sync once more

More in How agents stay current.

Moving and removing

• Move the agent to another machine: on the agent's page, Danger zone → Re-install gives you a new command. Run it on the new machine; the agent keeps its name and history.
• Remove the agent: Danger zone → Destroy deletes the agent in the app (type its name to confirm). For a self-hosted machine there is no cloud server to terminate, so the machine itself keeps its software, but its token stops working: it can no longer check in or fetch the agent ops. Then stop it on the machine, and reinstall or wipe the machine when you reuse it:

sudo systemctl disable --now kadmo-ops-sync.timer sidebutton.service

Troubleshooting

Message or symptom	Cause	Fix
"must run as root (curl … | sudo bash)"	The script ran without sudo	Pipe it into sudo … bash as in Step 2
"PORTAL_URL is required …"	The command lost its last line	Copy the whole command again
"AGENT_TOKEN is required …" / "AGENT_NAME is required …"	A variable is missing	Copy the whole command again
"failed to download or extract …"	No outbound HTTPS to GitHub	Allow outbound HTTPS to github.com, then run again
"unknown AGENT_RUNNER=…"	AGENT_RUNNER names a variant that does not exist	Leave AGENT_RUNNER unset
The install finishes, but the agent never appears Online	The token was used or had expired (60 minutes), or the machine cannot reach app.kadmo.ai	Reveal a fresh token and run again; check outbound HTTPS to the app
"could not download …/kadmo-ops-sync.mjs — the agent ops are not set up" or "agent ops sync attempt N did not finish"	The app was unreachable during the install	Nothing to do: the timer tries again every 5 minutes. journalctl -u kadmo-ops-sync shows why
The agent is Online but takes no jobs and its live desktop does not open	The app cannot reach machines outside Kadmo's network in this release	See the note at the top of this page

Related

• Agents: where agents run, agent apps, holds and updates
• Create an agent in your cloud