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.
- Create an account and add credit under Billing in the console (or redeem a voucher).
- Connect your agent to the remote MCP endpoint
/mcp, or sign in the CLI withagentcloudctl login. - 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).
- Authorization code + PKCE (S256 required) for agents with a browser. Redirect URIs: https, http loopback (any port) or a private-use scheme.
- Device authorization grant (RFC 8628) for terminals and headless agents:
POST /oauth/device_authorization, the user approves at/device. The built-in public client isagentcloud-cli. - Dynamic client registration (RFC 7591) at
POST /oauth/register; public (none) or confidential (client_secret_basic/_post) clients. - Access tokens (
acoa_…) live 1 hour; refresh tokens (acor_…) rotate on every use and reusing an old one revokes the whole authorization. Revoke withPOST /oauth/revoke(RFC 7009) or in the console.
| Scope | Allows |
|---|---|
sandboxes | Create, run commands in, stop and delete sandboxes (consumes credit). Default. |
billing:read | Balance, ledger, payments, pricing. Default. |
billing:topup | Create payment links the user completes; redeem vouchers. |
billing:charge | Charge 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
- Payment link (always safe):
billing_topup_link/POST /v1/billing/checkout {"amount_cents":2000,"save_payment_method":true}returnscheckout_url. The agent shows it to the user, who pays with card, wallet or a bank method; then pollbilling_payment_status. - Charge within a limit: with
billing:charge,billing_charge/POST /v1/billing/charge(anIdempotency-Keyis required) charges the saved method immediately. Refused with402 spend_limit_exceededbeyond the grant's monthly limit; cards that require authentication fail and the agent should fall back to a payment link. - Vouchers:
billing_redeem_voucher/POST /v1/billing/redeem. - 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.
| Endpoint | Scope |
|---|---|
GET /v1/account | any |
GET|POST /v1/sandboxes, GET /v1/sandboxes/{id}, /health, /events | sandboxes |
POST /v1/sandboxes/{id}/start|stop|restart|delete | sandboxes |
GET|POST /v1/sandboxes/{id}/jobs, GET …/jobs/{job}, …/logs?offset=, POST …/cancel | sandboxes |
GET /v1/usage, GET /v1/providers | sandboxes |
GET /v1/pricing | public |
GET /v1/billing/balance, /ledger, /payments, /payments/{id} | billing:read |
POST /v1/billing/checkout, POST /v1/billing/redeem | billing:topup |
POST /v1/billing/charge | billing: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.