Docs menu

Agents and control

Hosted agents

Set up an agent that runs on CLI on a schedule or when something happens, with its own capped key and a report after every run.

Explain it

A hosted agent is an AI agent that runs on CLI itself, so something can watch your project or fix it while you're away. You give it instructions, an AI model, and a schedule or events to wake on, and it leaves a report after every run.

How to do it: in project settings, open Hosted agents, write what it should do (for example "every morning, check for failed deploys and fix them"), choose when it runs and its spending limit, and save.

It works through its own key with a cap, and you can pause it at any time.

A hosted agent runs on CLI itself, so something can check on your project or fix it while nobody is around. You give it instructions, a model, and a schedule or events to wake on; it works through its own capped key and leaves a report after every run.

What a hosted agent is

  • It uses the same MCP tools as any other agent, and reads the same skill file.
  • It acts through its own project key, so your rules for agents, approvals, budgets and the key's spend cap apply exactly as they do to any agent (see /docs/agent-permissions).
  • It never gets a wallet, can't add credit, can't create projects, and can't add people or other agents.
  • It never waits for a person. Nobody is watching a run, so when something needs you (an approval, a secret, money, a judgment call) it finishes and says so in its report.

Good uses are a nightly check that backups ran and nothing is oversized, a look at every failed deploy as it happens, or a first response when a service goes down.

Create a hosted agent

Only a signed-in project admin can create one. A key can't, so an agent can never widen its own access.

In the dashboard:

  1. Open the project, go to Settings, then Hosted agents.
  2. Press Add a hosted agent.
  3. Give it a name and instructions, for example: "Every morning, check every service's health and error rate. If something failed overnight, find out why and fix it if the fix is a restart or a rollback. Report what you found."
  4. Pick a model (see below).
  5. Set a schedule, tick the events under Also run when, or both.
  6. Set its spending cap and save.

With the API:

API
POST /v1/projects/:id/hosted-agents
JSON
{
  "name": "night-watch",
  "provider": "cli",
  "instructions": "Check every service's health and error rate. If a deploy failed overnight, find out why and roll back if needed. Report what you found.",
  "schedule": "0 6 * * *",
  "triggers": ["deploy_failed", "service_down"],
  "spendCap": 5000000
}

Schedules and events

A schedule is a 5-field cron expression in UTC (or @hourly, @daily). Hosted agents run at most every 15 minutes, since each run costs model tokens.

Events it can wake on:

EventWhen
deploy_failedA deploy failed
service_downA service stopped answering health checks
error_newA new kind of exception appeared
cron_failedA cron job failed
low_balanceCredit dropped below your alert
budget_warningThe month's spend passed 80% of the budget
change_readyA proposed change was built and is ready to review
approval_resolvedSomeone approved or denied a request

The event's details are passed to the agent with its instructions. You can also start a run by hand at any time with Run now or POST /v1/hosted-agents/:id/run.

Models

ChoiceWho pays for tokens
CLI's model ("provider": "cli")Billed per token to the project's credit
Anthropic, with your keyYour Anthropic account
OpenAI or a compatible API, with your key (with an optional base URL)That provider

When you bring your own key, CLI stores it sealed and never shows it again.

Its own capped key

Each hosted agent gets a project key of its own, named hosted agent: <name>, with:

  • the agent role, so your rules and approvals apply;
  • the read and deploy scopes by default (you can choose others when you create it);
  • a spend cap, $5 unless you set another.

Only the project owner can change a hosted agent's spend cap later. Deleting a hosted agent revokes its key.

Reports

Every run ends with a short report, written to be read later: what changed or what's wrong first, or one line if all is well. Reports never include secret values.

The report goes out as an agent_report event, so your alert channels (Slack, Discord, Telegram, a webhook) can send it to you. It carries the run's status, how many steps it took and what it cost.

In the dashboard: press Runs on the agent to see each run: why it started, every tool call, tokens used, cost and the report. Tool calls that could show secrets (setting variables, reading connection URLs, running SQL or commands) are hidden in the stored transcript.

With the API:

API
GET /v1/hosted-agents/:id/runs

A run ends as done, cut_off (it hit its step or token limit), failed, or skipped (no credit left, or its daily tokens used up).

Cost controls

Several limits keep a hosted agent's cost bounded:

  • A daily token cap per agent, over a rolling 24 hours (500,000 tokens by default). Once it's used, runs are skipped.
  • A step limit per run (20 by default, up to 40).
  • One run at a time. A run that's still going blocks the next.
  • Event cool-down: an agent woken by events runs at most once every 10 minutes for them.
  • A 15-minute minimum schedule.
  • Its key's spend cap, and your project's budget and daily limit for agents, for anything it starts.

Each run costs a small fixed amount to cover running it ($0.002 on the default settings), plus tokens if it uses CLI's model. Both come out of the project's credit and show under Hosted agents in the money flow (see /docs/billing).

Pause, change or delete

In the dashboard: use Pause (or Resume) and Delete on the agent in Hosted agents.

With the API:

API
PATCH /v1/hosted-agents/:id
JSON
{ "status": "paused" }

The same call changes instructions, schedule, events, step and token limits, or the model. DELETE /v1/hosted-agents/:id removes it and revokes its key. Changing or deleting one needs a signed-in admin.

Ask your agent:

"List the hosted agents in this project and what their last runs reported."

Agents can read hosted agents and their runs, but only a person can create or change one.