◈ AgentCloud

Quick start

Base URL: https://agentcloud.example. Every account is a tenant with a prepaid credit balance. Sandboxes are VMs; jobs are commands run inside them in resource-limited containers.

  1. Create an account and add credit under Billing in the console (or redeem a voucher).
  2. Connect your agent to the remote MCP endpoint /mcp, or sign in the CLI with agentcloudctl login.
  3. Approve the agent in the browser. Choose its permissions and, if you allow it to charge your card, a monthly limit.
agentcloudctl login
agentcloudctl balance
agentcloudctl create --wait my-box
agentcloudctl run SANDBOX_ID -- python3 -c "print('hello')"
agentcloudctl delete SANDBOX_ID

MCP

Remote server (recommended)

Endpoint /mcp speaks the Streamable HTTP transport (JSON responses, stateless; protocol versions 2025-06-18, 2025-03-26 and 2024-11-05). Unauthenticated requests get 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp", so compliant clients discover the authorization server, register themselves and run the OAuth flow automatically.

claude mcp add --transport http agentcloud https://agentcloud.example/mcp

Clients that cannot do OAuth may send an API key instead: Authorization: Bearer acak_….

Local stdio server

agentcloud-mcp uses the credentials stored by agentcloudctl login (refreshed automatically) or AGENTCLOUD_TOKEN. It can additionally inject local secrets into jobs (AGENTCLOUD_MCP_SECRETS=NAME=LOCAL_ENV,…) without the values passing through the model.

Tools

sandbox_create, sandbox_wait_ready, sandbox_list, sandbox_get, sandbox_health, sandbox_events, sandbox_start/stop/restart/delete, job_run, job_get, job_list, job_logs, job_cancel, usage_get, providers_list, account_get, billing_pricing, billing_balance, billing_ledger, billing_topup_link, billing_payment_status, billing_charge, billing_redeem_voucher.

OAuth: agents acting on your behalf

AgentCloud is an OAuth 2.1 authorization server. Discovery: /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource (RFC 9728).

ScopeAllows
sandboxesCreate, run commands in, stop and delete sandboxes (consumes credit). Default.
billing:readBalance, ledger, payments, pricing. Default.
billing:topupCreate payment links the user completes; redeem vouchers.
billing:chargeCharge the saved payment method, up to the monthly limit the user set at consent.

The user can untick any requested permission on the consent screen. billing:charge is only granted together with a positive monthly limit. Account settings, API keys and connected agents can only be managed by a signed-in person, never by an agent.

Billing and payments

Prepaid credit in the account currency. VM time is metered every minute at the hourly price locked in when the sandbox is created (see GET /v1/pricing). Creating or starting a sandbox needs at least one hour of credit. When the balance reaches zero the account is suspended: ready sandboxes are stopped and new work is refused; after the grace period (default 72 hours) the sandboxes are deleted. Any top-up resumes the account.

How an agent pays

  1. Payment link (always safe): billing_topup_link / POST /v1/billing/checkout {"amount_cents":2000,"save_payment_method":true} returns checkout_url. The agent shows it to the user, who pays with card, wallet or a bank method; then poll billing_payment_status.
  2. Charge within a limit: with billing:charge, billing_charge / POST /v1/billing/charge (an Idempotency-Key is required) charges the saved method immediately. Refused with 402 spend_limit_exceeded beyond the grant's monthly limit; cards that require authentication fail and the agent should fall back to a payment link.
  3. Vouchers: billing_redeem_voucher / POST /v1/billing/redeem.
  4. Bank transfer / invoice: arranged with the operator, who credits the account (audited ledger adjustment).

Auto-recharge (console → Billing) tops up the saved method when the balance falls below a threshold. Charges made with API keys are capped by the account's own monthly limit (0 by default, i.e. disabled).

REST API

JSON over HTTPS. Authenticate with Authorization: Bearer and an API key (acak_…, created in the console) or an OAuth access token. Errors look like {"error":{"code":"insufficient_credits","message":"…"}}. Send Idempotency-Key on creates and payments to make retries safe.

EndpointScope
GET /v1/accountany
GET|POST /v1/sandboxes, GET /v1/sandboxes/{id}, /health, /eventssandboxes
POST /v1/sandboxes/{id}/start|stop|restart|deletesandboxes
GET|POST /v1/sandboxes/{id}/jobs, GET …/jobs/{job}, …/logs?offset=, POST …/cancelsandboxes
GET /v1/usage, GET /v1/providerssandboxes
GET /v1/pricingpublic
GET /v1/billing/balance, /ledger, /payments, /payments/{id}billing:read
POST /v1/billing/checkout, POST /v1/billing/redeembilling:topup
POST /v1/billing/chargebilling:charge

Status codes: 401 bad or missing credentials, 402 insufficient credit, suspended account or spend limit, 403 missing scope or human-only action, 409 state or idempotency conflict, 429 rate limited.