Skip to main content
A cloud agent is an agent definition from your Library that runs in the cloud instead of on your machine. The Console compiles it into an Anthropic managed agent and runs it with your organization’s Anthropic API key. The Console keeps the key (encrypted), the budgets, the approvals and the roles; ravi cloud drives it with your ravi login session.
You need a ravi login session, a Console project (--project <slug>, or your default project) and an agent published to the Library with ravi agents publish.

​
Braking

Everything that spends money, creates provider objects or sends a secret is braked: without --execute the command prints its plan and exits 3, and nothing is sent. Stopping, denying, archiving, removing and disabling apply at once. Every command takes --json.

​
Set the organization’s key

An owner or admin sets the Anthropic API key once. The key is read only from redirected stdin, and only with --execute; it never comes back, only its last characters.
--monthly-alert notifies owners and admins when the month’s cost passes the amount. Agents never set the key.

​
Deploy and run

  • --budget <usd> (0.5 to 200) caps one run; without it the agent’s budget applies (5 by default). A run that reaches it ends budget_exceeded.
  • --repo owner/name[@branch] mounts a repository the organization’s GitHub App covers; repeat it for more.
  • --idempotency-key <key> makes a retry return the same run instead of starting a second one.
  • runs follow --json prints one event per line and ends with {"type":"run","run":{...}}.
Run statuses: starting, running, waiting_approval, completed, failed, stopped, budget_exceeded.

​
Approvals

With tools.writes: "ask" (the default), a run pauses in waiting_approval before a write outside its container, such as an MCP tool that changes something. Approving makes the run act as you.
An agent turn of someone other than the operator cannot approve. You can also decide in the Console’s run page.

​
Files

Files come through the Console. A download never overwrites an existing file; use an empty folder. Two outputs that would land on one path (also when only the case differs) are refused before anything is written.

​
Schedules

Each tick starts a paid run as the person who scheduled it, with the schedule’s prompt (default: the agent’s HEARTBEAT.md) and budget.

​
Run a task in the cloud

The task runs as a cloud run of the local agent’s Library definition: the one it was installed from, or a Library agent with the same id. The task becomes in_progress, and the daemon follows the run every 30 seconds:
  • a pending approval reaches the session (--report-to, or the session that dispatched) with the approve command;
  • when the run ends, the task becomes done or failed and the result reaches the session once, quoted as untrusted text.
An agent without a Library definition is refused with CLOUD_AGENT_NOT_PUBLISHED. From a terminal, pass --report-to <session>: a cloud task needs a session for its result (CLOUD_TASK_SESSION_REQUIRED otherwise).

​
The cloud block

The agent’s agent.json can carry a cloud block. ravi agents publish validates and publishes it; ravi agents install writes it back, so publishing again keeps it. Every key is optional:
The block never carries credentials: keys that look like secrets (token, secret, password, apiKey, authorization, cookie), URLs with a user or a query string, and unknown keys are refused with CLOUD_AGENT_DEFINITION_INVALID.

​
Errors