Skip to main content
Agent37 Cloud provides persistent sandboxes for code, services, and agents. Each sandbox is an instance. A template chooses the software installed inside it. The Sandbox API manages your instances, and authenticated HTTPS URLs let you reach the services they run. Choose an agent template when you also need the Agent API for conversations and tools. An instance can also be a full Linux VM: set "type": "vm" for its own kernel, Docker-in-Docker, Compose, or nested KVM. Use agent37-ubuntu for Docker and a Linux desktop, or agent37-android for Android 14 with ADB and a browser screen. Both use the same Sandbox API.

​
Two planes, one key

Both planes take the same sk_live_ key, in two different headers. api.agent37.com takes Authorization: Bearer sk_live_.... Everything on agent37.app (instance URLs and sandbox.agent37.app) takes the raw key as X-Agent37-Key: sk_live_..., which leaves Authorization free for your own app running inside the instance. Mint keys in the dashboard; each key is scoped to one workspace. On the Sandbox API the key selects your workspace. On an instance URL, the platform edge authenticates the key, verifies the instance belongs to your workspace, and forwards the request to the service listening on the requested port. On an agent template’s default port, that service is the agent gateway. A key can carry an IP allowlist: up to 20 IPs or CIDR ranges (IPv4 and IPv6), edited per key in the dashboard. A restricted key only works from those addresses, on both planes; anywhere else it gets 403 ip_not_allowed with the observed IP in the message. An empty list means the key works from any IP. Signed URLs and public ports carry their own authorization and are not affected, so a browser link keeps working wherever it is opened. Create and manage a sandbox through the Sandbox API, regardless of which template it runs:
Instance URLs require auth on every request: the X-Agent37-Key header for API calls, or a time-boxed signed URL to open a preview URL in a browser tab. An unauthenticated request gets a 401.

​
The resource model

​
Every port has a derivable URL

Nothing about ports is declared per instance:
  • The instance URL, https://{instanceId}.agent37.app, routes to the template’s default_port (3737, the gateway, unless the template says otherwise). On the default template, agent37-hermes, that makes it the chat URL.
  • Every other port is reachable at its preview URL, https://{instanceId}-{port}.agent37.app, for example https://ab12cd34ef-9119.agent37.app.
  • A port can also get a permanent unauthenticated URL; see Public ports.
See Instance and preview URLs for how routing and authentication work, and Templates for default_port on your own images.

​
Agent template resources

These resources belong to the Agent API supplied by agent templates. A custom image or a web app such as n8n does not acquire a chat API just by running in a sandbox.
The agent is not the model. The template installs the agent software, the gateway inside the instance runs your sessions on it (Hermes, OpenClaw, Claude Code, Codex, Grok, OpenCode, and Pi are the live agents today), and the model is the LLM the agent thinks with, set as model on a turn (plus provider on Hermes; see Models for how each harness applies it).

​
How they fit together

  • Create an instance for a user or workload with POST /v1/instances on the Sandbox API. It keeps files, connected accounts, and memory across every session. An instance does not have to run around the clock: create it with auto_sleep: true and the platform checkpoints it to sleeping once it has been idle past its idle_timeout_seconds, billing disk alone while it sleeps; any request to its URL wakes it transparently (a few seconds for a restore, about two minutes when the instance has to be rebuilt). See Auto-sleep.
  • On an agent template, start a session by sending a message to the instance’s own URL: POST https://{instanceId}.agent37.app/v1/responses. Omit session_id and the gateway mints a new session; the reply carries the session_id you reuse to continue the thread. See Sessions.
  • Each message produces a response. Stream it live with stream: true (see Streaming), or reconnect a dropped stream with GET /v1/responses/{id}/stream.

​
One wallet, per-instance caps

Your workspace has exactly one pot of money: the wallet, funded by top-up from the billing dashboard. Two things draw on it:
  • Compute. Each instance is metered per minute: the full rate while running, disk alone while stopped or sleeping. See Billing.
  • Managed usage. Every instance gets managed LLM, Brave search, and Composio credentials, metered at cost as the agent uses them. They arrive as environment variables inside the container, so a custom image can use them too; see Managed services in your image. Model usage on agent37-claude-code and agent37-codex is the exception: Claude Code runs on your own Anthropic account and Codex on your own OpenAI account, so Agent37 never supplies or bills their model spend.
Per-instance budgets are caps, not money. A budget bounds how much managed spend an instance may pull from the wallet: a monthly cap that resets each UTC month (default $0) plus one-time top-up headroom. Raising a cap moves no funds; an instance with a generous cap and an empty wallet still gets refused.

​
Conventions

  • Instance ids are bare 10-character lowercase alphanumerics, like ab12cd34ef. No prefixes. The id doubles as the DNS label in the instance URL.
  • Session and response ids are 32-character hex strings minted by the gateway, like 7f3e0b6c52a949d2b1c4a8e9d0f31726.
  • Money is integer micros: USD x 1e6, in *_micros fields.
  • Timestamps are epoch seconds on the Sandbox API and epoch milliseconds on the Agent API. The App integrations endpoints are the exception: they pass Composio’s native shapes through unchanged, with millisecond timestamps.
  • Lists wrap results in { "data": [...] }. Instance and session lists are newest first. (The App integrations endpoints again pass Composio’s native paginated and connection shapes through instead.)
An instance’s status is one of provisioning, running, stopping, stopped, starting, restarting, updating, sleeping, waking, failed, deleting, or deleted; a response’s status is in_progress, completed, failed, or cancelled.

​
Next steps

Create an instance

Start a persistent sandbox with one request.

Bring your own image

Choose the tools and services your sandbox runs.

Instance and preview URLs

Reach any service over authenticated HTTPS.

Use an agent template

Add conversations with a hosted harness.