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
| Your cloud | Your own machine | |
|---|---|---|
| Runs on | Your AWS or Hetzner account | Any Ubuntu 24.04 machine you control |
| How you get one | The create-agent wizard (Create Agent) | The one-line installer from an agent's page |
| Machine cost | Billed by your cloud provider | Yours |
| Card chip | Your profile and size | BYO-VM on the agent page |
| Guide | 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:
- AWS works when the connection names an agent subnet that is peered with Kadmo's network: see The agent subnet.
- 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).
| 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 |
| Updating | An update is on its way to the agent, or its components pass is installing one; it takes no new job until the update window ends (see Agent updates) |
| Held | A Self Update stopped at its ceiling may still be running; the agent takes no job until the session is gone or you press Resume (see Holds) |
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
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 BYOK › 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 account |
| 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 | Accounts whose plan includes own model providers (see Your own keys) |
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 provider: Kadmo, or your own key once one is connected on BYOK › Providers. The Agent Apps tab names it, with its model, above the list. A new account's Kadmo app starts on a default model that depends on the account's plan; an admin changes it on the app. 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".
Parallel jobs
By default 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.
An agent's owner can raise the limit. Under Capabilities → Agents → Owner settings, Parallel jobs sets how many tracked jobs the agent runs at once, from 1 to 4, and the block shows how many are running. The number takes effect once the agent's runtime keeps a job context per session, which the Kadmo Agent Runtime 0.2.0 does and a Self Update brings (Agent updates); until then the agent keeps one job, whatever the number says.
Above one, a job runs beside another only when both allow it. Each workflow says whether it can share an agent, and what a job holds decides the rest:
| A job holds | Runs beside |
|---|---|
| The whole agent: Self Update, Wipe workspace, an app's edit session | Nothing |
| Its workspace | Anything that is not exclusive and not in the same workspace |
| The agent's browser | Anything that is not exclusive, while a browser slot is free |
| Nothing | Anything that is not exclusive |
Browser slots, beside Parallel jobs, sets how many browser-holding jobs the agent runs at once, from 1 to 4 and never more than its parallel jobs. Every agent has one browser slot until its runtime reports a browser session per job; the number waits for that.
The fleet card shows the slots taken, for example 2/3. Start now on a queued item asks Start over capacity? before it places a job past the limit, or beside one the row cannot share an agent with, and Start anyway forces it. Pull repos always queues behind the running jobs.
Agent updates
An agent's page lists what it runs, item by item, in its Items block: the components it was created with and any added since, its runtimes (the Kadmo Agent Runtime, Claude Code, and the runners, the helper scripts and timers on the machine), and the skills and files of its workspaces. Each row shows the version it is at and what is on its way:
| Row reads | Meaning |
|---|---|
Installed x.y.z | On the machine at this version |
Update pending → target | A newer target is known; it lands at the next update the rule allows |
| Waiting | Asked for, and waiting for an update window: the agent is busy, or the change is automatic and Auto Update Agent is off |
| Installing | The agent's components pass is installing it now |
| Failed | The install failed; the row names the cause, and Retry tries again. A version that does not come up is rolled back, and the row says why |
| Applied (skills and files) | Delivered to the agent's workspaces at the version the workspace holds |
The block appears once the agent's runtime reports its components; an agent created earlier shows Self Update alone until it does.
Targets
Each runtime item has a target: the agent's pin where its owner set one (the runners' commit, the runtime's version, on the agent page), else the latest Kadmo serves. A component from the catalogue has a version where the catalogue pins one.
When a change lands
| Change | Idle agent | Busy agent |
|---|---|---|
| An apply: Save & apply on a workspace, Apply config on the agent, Add component, Retry, a dispatched Self Update | Now | Remembered, and delivered when its last job ends. Until then the agent takes no new job, and the fleet reads Updating |
| Apply to Busy, on the workspace and in the Add dialog | Now | Now, for environment and config files, skills, files and component installs; git projects and a runtime restart wait for the jobs to end |
| Automatic: a target moved, a failed item retried, an item found missing | Only with Auto Update Agent on, at the agent's next idle moment | Only with the switch on, once idle |
| Always, whatever the switch: the first delivery after provisioning, credentials and environment, the agent ops and your account's skill packs | Now | Now |
Auto Update Agent is the owner's switch under Capabilities → Agents → Owner settings, off by default. With it off, only an apply and the always-on lanes reach the agent, and a new target waits for your Self Update. Accounts the agent is shared into see the switch read-only.
The agent applies changes in a components pass that runs every ten minutes and whenever the app asks for it. The pass asks the app for a window, installs what the window allows, and reports. An apply that waits for a component holds the agent for one pass at most; a change that cannot be delivered expires after a day, and an admin can clear it on the agent page. A component that restarts the runtime (Docker, for example) and a new runtime version restart kadmo.service last, and only when no job and no Claude Code session runs on the agent. A session a finished job left behind counts until it ends, which takes up to about an hour, so the row keeps reading Update pending with the restart owed until then.
Self Update
Self Update (Run Job → Self Update) brings an agent to its targets whatever the switch says: it syncs the workspace repositories, starts a components pass that moves the runtime, Claude Code, the runners and the components, and runs the ops sync once more. The job ends within 20 minutes and reports what ran. What the pass could not take during the job is delivered when the job has ended, under an update window of up to 15 minutes. An agent whose runtime has never run a components pass gets no window: it takes work again as soon as the job has ended. A version that does not come up is rolled back, and the row names the cause.
Run it after a Kadmo release, when an agent behaves as if it runs old code, or to move an agent to a new runtime version. The runtime restart lands as described above.
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.
- Update hold: while an apply is on its way to a busy agent, and inside the update window its components pass installs under, the agent takes no new job; the fleet reads Updating. It ends with the pass's report, with the window, or when an admin clears the apply on the agent page; clearing a Self Update's drops its version move, and the button and the toast say so. See Agent updates.
- Session hold: a Self Update stopped at its 20-minute ceiling whose stop could not be confirmed holds the agent; the card reads Held, with Resume. The hold ends when the agent no longer lists the session, when you press Resume, or after 24 hours, and a pause under it is put back.
A held agent takes no work from the queue sweep. Start now on a queued item still sends work to a paused agent on purpose; across an update hold it asks first.
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 |
| The agent runtime, Claude Code, the runners and the components | The agent's components pass, every ten minutes, under the update rule; Self Update brings every item to its target at once | Automatic changes with Auto Update Agent on, or when you run Self Update (see Agent updates) |
Run Self Update after a Kadmo release, or when an agent behaves as if it runs old code; what it does is under Self Update. 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