Skip to main content
POST
Authenticate with Authorization: Bearer sk_live_... on https://api.agent37.com.

Request body

The examples include every optional field. Omit any field to use its default.
string
default:"agent37-hermes"
A system or workspace template name. Defaults to agent37-hermes. Add @<version> to pin a published release. See Template selection for harness requirements and version rules.
object
The instance shape, for example { "cpu": 2, "memory": 4, "disk": 6 }. Omitted, it uses the smallest shape, 2 vCPU / 4 GB. See Instance sizing for the four available shapes. Free workspaces (before your first top-up) run the 2 vCPU / 4 GB shape; the larger 4/8, 8/16, and 16/32 shapes return 403 tier_limit until you top up. Disk is any whole number of GB within the shape’s range, and defaults to 4, 6, 12, or 24 GB by shape when omitted. Any other combination returns 400 invalid_request listing the valid shapes.
string
default:"default"
default is used when you omit type, and for most harnesses it is all you need. performance runs the instance on dedicated cores, for heavy work such as computer use, at 4x the default compute rate. See Default and Performance instances.burstable is an experimental instance type for low average CPU and RAM usage, starting at $1/month. Apply here to enable it for your workspace.
string
An opaque tag for your own attribution, typically your end user’s id. Stored, never interpreted, echoed back on the instance object.
string
A label for the instance.
object
Your own key/value pairs. Stored, never interpreted.
object
Environment variables for the container, as string key/value pairs. Set once at create and replayed on every restart, update, and wake. Up to 64 entries and 64 KB in total; keys are uppercase letters, digits, and underscores starting with a letter; values are strings of up to 4096 characters. See Environment variables.
object
Caps on this instance’s managed usage (managed LLM, Brave search, and Composio calls), in micros (millionths of a dollar): monthly_cap_micros resets each UTC month, credit_micros adds one-time headroom that persists until spent. Both default to 0, so managed calls are refused until you raise one. These are ceilings, not money; spend still draws the workspace wallet. See Budgets.
boolean
default:"false"
Opt the instance into auto-sleep: once no bytes have moved through its URLs for idle_timeout_seconds, it is checkpointed to sleeping and bills disk alone until a request wakes it. Awake minutes bill the ordinary compute rate.
integer
default:"900"
How long the instance must be idle before it sleeps, in seconds. An integer from 300 to 86400 (five minutes to one day). Only meaningful with auto_sleep: true.
object[]
Ports to expose at permanent unauthenticated URLs, each { port, prefix?, label? }, for webhooks and other callers that can’t send a credential. See Public ports, or follow the end-to-end Hermes webhook setup for port 8644.

Defaults

POST /v1/instances returns 201 with the full instance object once status is running. Every field is optional, so a POST with no body works: you get the default template (agent37-hermes) on the smallest shape, 2 vCPU / 4 GB.

Funding and readiness

Creating an instance requires one day of compute at its running rate in your workspace wallet, but debits nothing: the balance check is the create gate (below it, the create fails with 402 insufficient_balance and nothing is provisioned), and the meter only starts when the instance first reaches running. How many instances the workspace can hold, sleeping and stopped ones included, is set by your instance limit, which rises as you top up. See Billing. For agent templates, set a managed-service budget before using the managed model. The default budget is zero; shell commands do not need managed-model spending. Poll GET /v1/health on the returned url until healthy is true, then send a message. running means the computer is up; the agent can still be booting. Follow Send your first agent message for the complete agent setup. For shell commands and services, start with the Quickstart.

Response

201 with the full instance object. The example response shows only id, status, and url.

Template selection

A template name. agent37-hermes (full Hermes, with a headless browser) is the default; agent37-openclaw (OpenClaw, with a headless browser), agent37-claude-code (Claude Code, which needs your own Anthropic account connected before chat turns work), agent37-codex (Codex, which needs your own OpenAI account connected before chat turns work), agent37-grok (Grok, which needs your own xAI API key set before chat turns work), agent37-opencode (OpenCode, which runs on the managed model out of the box), agent37-pi (Pi, the minimal harness, also on the managed model out of the box), and agent37-n8n (n8n, a workflow automation web app with no chat API; its editor gets a public URL on create) are the other system templates. You can also pass one of your own workspace templates by name. Any name takes an optional @<version> to pin a published release: a tag on system templates (agent37-hermes@<tag>), a revision number on workspace templates (my-agent@2). Pin when your creates must be reproducible; the bare name follows the latest release. Unknown names and unpublished versions return 400 invalid_request. Direct image references are rejected with 400: register a template first, then pass its name.

Capacity and limit errors

See Errors for the full catalog and the error envelope.