Appearance
Agents
An agent is the machine that does Kadmo's work: a Linux virtual machine with a full desktop, Google Chrome and a terminal, running a coding app that picks up jobs, works in your repositories and reports back to the app. This page explains where agents run, how you create one, which coding app and model it uses, and how Kadmo keeps every agent up to date.
What an agent is
Each agent is one machine with:
| Part | What it does |
|---|---|
| Desktop and Chrome | A full XFCE desktop with Chrome, so the agent can open and test web apps the way a person would. You can watch it live from the app |
| Terminal and coding app | The coding app (Claude Code) runs each job in a terminal on the desktop |
| Agent runtime | A small service that talks to the app: it takes jobs, reports status, health and screenshots, and serves your skill packs to the coding app |
| Workspace | The folder where the agent checks out the repositories of the workspaces you assign to it |
The app sends work to an agent as jobs: a task, a playbook step, a chat, an automation or a run you start yourself. Every job is tracked with its status, cost and transcript on the Jobs page.
Where an agent can run
| Hosted by Kadmo | Your cloud | Your own machine | |
|---|---|---|---|
| Runs on | Kadmo's cloud | Your AWS or Hetzner account | Any Ubuntu 24.04 machine you control |
| How you get one | Request Hosted Agent on the Agent Fleet page | The create-agent wizard (Create Agent) | The one-line installer from an agent's page |
| Machine cost | Kadmo's | Billed by your cloud provider | Yours |
| Card chip | Hosted · Kadmo | Your profile and size | BYO-VM on the agent page |
| Guide | Request a hosted agent | Create an agent in your cloud | Self-hosting |
In this release
The app reaches every agent over Kadmo's private network. That decides what works today:
- Hosted by Kadmo works as described below.
- AWS works when the connection names an agent subnet that is peered with Kadmo's network. Kadmo sets up that peering with you: book a call. See Connect AWS.
- Hetzner: you can connect an account, but the app refuses to launch agents there ("Hetzner agents have no private network this app can reach yet").
- Your own machine: the installer registers the machine and it reports its status, but the app cannot reach it, so it takes no jobs and its live desktop does not open.
The Agent Fleet page
Open Agent Fleet in the sidebar. Each agent is a card with its live screen, status, queue and current job. The header shows how many agents your account owns against its limit (for example 3 / 100 agents), and how many Kadmo hosts for you (· 2 hosted).
| Status | Meaning |
|---|---|
| Online | The agent checked in within the last 5 minutes and has no job |
| Busy | The agent is running a job |
| On hold | The agent is paused and takes no automatic work (see Holds) |
| Provisioning | A new agent is being created in your cloud |
Use the search box and the Role, Status, Profile and Identity filters to narrow the list. Run Job starts a workflow on an agent you pick; Jobs → opens the ledger of everything the fleet has run.
Creating an agent
Request a hosted agent
A hosted agent runs on Kadmo's cloud, so there is nothing to connect.
- On Agent Fleet, click Request Hosted Agent below the fleet. When your account has no hosted-agent allowance, the button opens Kadmo's booking page instead, and the team sets the agents up after the call. On an empty fleet the page shows only the cloud setup, so for your first hosted agents book a call.
- Pick how many agents and the LLM provider:
- Claude Opus/Sonnet: billed to your Kadmo credit per token, on the models your plan includes. Nothing to connect. This is the recommended default.
- None — bring your own (
not metered): sign in to Claude Code on the agent's live desktop yourself. See Use your Claude subscription.
- Add an optional comment (repositories, stack, what you plan to run) and click Create agents.
A Setting up strip shows while the Kadmo team prepares them, usually within the hour. You can cancel the request from the strip. The agents then appear on the page with a Hosted · Kadmo chip.
Create an agent in your cloud
Account admins create agents in a connected AWS or Hetzner account with the four-step wizard: Software, Machine, Roles & tools and Name & launch. The wizard shows a live build sheet with the estimated monthly cost, and a new agent reports Online in about ten minutes. The full walkthrough is Create an agent in your cloud; connecting the cloud first is Connect AWS or Connect Hetzner.
Agent apps: the coding app and its model
An agent app decides which coding app runs an agent's jobs and which model provider it calls. Manage them on Agent Apps in the settings sidebar. Account admins can add and edit apps; other members see the list read-only.
| App | What it is | Who can use it |
|---|---|---|
| Kadmo | Claude Code on Kadmo's models, paid per token from your Kadmo credit. Every account has it; on a new account it is the default | Every plan |
| Claude Code (subscription) and other direct apps | Claude Code signed in with your own Claude subscription, or your own API key, gateway or cloud model account | Enterprise plan ("Your own keys are an Enterprise feature.") |
An agent uses, in order: the app a run asks for, the agent's Pinned app (agent page → Configuration → Agent apps), then the account's default app (Make default on the Agent Apps page). On a trial the Kadmo app starts on Claude Haiku 4.5; on every other plan it starts on Claude Sonnet 5.5. Credit and models are explained in The Kadmo provider.
To run agents on your own Claude subscription, see Use your Claude subscription.
Effort tiers
An effort tier is a named preset that sets how hard the coding app works on a job. For Claude Code a tier binds a Model and an Effort level. Every account starts with three tiers, Max, High and Medium, and admins can rename, reorder, add and delete tiers under Settings → General → Effort tiers. The tier you mark as default applies to every agent job that does not ask for another.
A tier can be set on a workflow, a playbook, a playbook step, and on a single run (the Effort tier picker in Run Job). The most specific explicit choice wins: a run's pick beats the step, the step beats the playbook, the playbook beats the workflow, and anything left unset falls back to the account default. Auto in a picker means "inherit".
One job at a time
An agent runs one job at a time. Work that arrives while it is busy waits in its queue, and work that is not pinned to an agent goes to any matching agent that is free.
Holds
A hold pauses automatic dispatch to an agent without stopping it.
- After a new cloud agent checks in, the app holds it for 15 minutes while the machine finishes its setup. The card shows
Paused · 15m left, the provisioning log says "Checked in — held 15 min while setup finishes", and the hold lifts by itself. To start sooner, use Resume now on the agent page. Agents on your own machine are never held. - Manual hold: on the agent page, Hold busy offers Hold 15 minutes, 1 hour, 3 hours, 6 hours or 1 day. Resume now releases the hold; Extend to 1 hour resets the timer.
A held agent takes no work from the queue sweep. Dispatch now on a queued item still sends work to it on purpose.
The agent page
Click an agent's name to open its page:
| Section | What you find |
|---|---|
| Live desktop | The agent's screen, live (account admins) |
| Active & queue, Activity | The running job, what waits, and recent events |
| Configuration | The agent's environment variables and its Agent apps (pinned app, which apps deliver their settings to it) |
| Agent token | Reveal Agent token: a single-use token and installer command to attach a machine as this agent (Self-hosting) |
| Danger zone | Reboot, Stop/Start (cloud agents only; storage is still billed while stopped), Re-install on another VM, and Destroy (terminates the VM and deletes the agent; you type its name to confirm) |
How agents stay current
You do not rebuild agents to pick up changes. Each agent keeps itself current in four ways:
| What | How it updates | When |
|---|---|---|
| Agent ops (the built-in roles, the workflows playbooks run, and their modules) | The agent asks the app for the current version with its own token and installs it only when it changed | Every 5 minutes |
| Public skill-pack library (kadmo-skill-packs) | Added as a registry on every agent and pulled with the registry update | Every 5 minutes |
| Your account's skill packs | Pulled from your account's pack repository; a pushed change reaches agents on the next sync | Every 5 minutes |
| Agent runtime and its helper scripts | The Self Update job: it syncs the workspace repositories, upgrades the agent runtime, refreshes the runner's helper scripts and runs the ops sync once more | When you run it (Run Job → Self Update) |
Run Self Update at the start of a shift, after a Kadmo release, or when an agent behaves as if it runs old code. Every step is a no-op when nothing changed, and a repository with local work (uncommitted changes, unpushed commits, another branch) is left as it is and named in the job's report.
Deleting an agent, or replacing its token, ends its access to the agent ops.
Related
- Create an agent in your cloud
- Use your Claude subscription
- Workspaces, which decide what an agent checks out
- Skill packs