curl -X POST \
https://api.agent37.com/v1/instances \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"template": "agent37-hermes",
"resources": {
"cpu": 2,
"memory": 4,
"disk": 4
},
"type": "default",
"user": "u_882",
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"env": {
"APP_ENV": "production",
"LOG_LEVEL": "info"
},
"budget": {
"monthly_cap_micros": 5000000,
"credit_micros": 1000000
},
"auto_sleep": true,
"idle_timeout_seconds": 900,
"public_ports": [
{
"port": 8080,
"prefix": "app",
"label": "My app"
}
]
}'
import requests
response = requests.post(
"https://api.agent37.com/v1/instances",
headers={
"Authorization": "Bearer sk_live_...",
},
json={
"template": "agent37-hermes",
"resources": {
"cpu": 2,
"memory": 4,
"disk": 4,
},
"type": "default",
"user": "u_882",
"name": "Production agent",
"metadata": {
"plan": "pro",
},
"env": {
"APP_ENV": "production",
"LOG_LEVEL": "info",
},
"budget": {
"monthly_cap_micros": 5000000,
"credit_micros": 1000000,
},
"auto_sleep": True,
"idle_timeout_seconds": 900,
"public_ports": [
{
"port": 8080,
"prefix": "app",
"label": "My app",
},
],
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances",
{
method: "POST",
headers: {
Authorization: "Bearer sk_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
template: "agent37-hermes",
resources: {
cpu: 2,
memory: 4,
disk: 4,
},
type: "default",
user: "u_882",
name: "Production agent",
metadata: {
plan: "pro",
},
env: {
APP_ENV: "production",
LOG_LEVEL: "info",
},
budget: {
monthly_cap_micros: 5000000,
credit_micros: 1000000,
},
auto_sleep: true,
idle_timeout_seconds: 900,
public_ports: [
{
port: 8080,
prefix: "app",
label: "My app",
},
],
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"status": "running",
"url": "https://ab12cd34ef.agent37.app"
}
Instances
Create an instance
Create a persistent sandbox from a template. All request fields are optional.
POST
/
v1
/
instances
curl -X POST \
https://api.agent37.com/v1/instances \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"template": "agent37-hermes",
"resources": {
"cpu": 2,
"memory": 4,
"disk": 4
},
"type": "default",
"user": "u_882",
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"env": {
"APP_ENV": "production",
"LOG_LEVEL": "info"
},
"budget": {
"monthly_cap_micros": 5000000,
"credit_micros": 1000000
},
"auto_sleep": true,
"idle_timeout_seconds": 900,
"public_ports": [
{
"port": 8080,
"prefix": "app",
"label": "My app"
}
]
}'
import requests
response = requests.post(
"https://api.agent37.com/v1/instances",
headers={
"Authorization": "Bearer sk_live_...",
},
json={
"template": "agent37-hermes",
"resources": {
"cpu": 2,
"memory": 4,
"disk": 4,
},
"type": "default",
"user": "u_882",
"name": "Production agent",
"metadata": {
"plan": "pro",
},
"env": {
"APP_ENV": "production",
"LOG_LEVEL": "info",
},
"budget": {
"monthly_cap_micros": 5000000,
"credit_micros": 1000000,
},
"auto_sleep": True,
"idle_timeout_seconds": 900,
"public_ports": [
{
"port": 8080,
"prefix": "app",
"label": "My app",
},
],
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances",
{
method: "POST",
headers: {
Authorization: "Bearer sk_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
template: "agent37-hermes",
resources: {
cpu: 2,
memory: 4,
disk: 4,
},
type: "default",
user: "u_882",
name: "Production agent",
metadata: {
plan: "pro",
},
env: {
APP_ENV: "production",
LOG_LEVEL: "info",
},
budget: {
monthly_cap_micros: 5000000,
credit_micros: 1000000,
},
auto_sleep: true,
idle_timeout_seconds: 900,
public_ports: [
{
port: 8080,
prefix: "app",
label: "My app",
},
],
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"status": "running",
"url": "https://ab12cd34ef.agent37.app"
}
curl -X POST \
https://api.agent37.com/v1/instances \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"template": "agent37-hermes",
"resources": {
"cpu": 2,
"memory": 4,
"disk": 4
},
"type": "default",
"user": "u_882",
"name": "Production agent",
"metadata": {
"plan": "pro"
},
"env": {
"APP_ENV": "production",
"LOG_LEVEL": "info"
},
"budget": {
"monthly_cap_micros": 5000000,
"credit_micros": 1000000
},
"auto_sleep": true,
"idle_timeout_seconds": 900,
"public_ports": [
{
"port": 8080,
"prefix": "app",
"label": "My app"
}
]
}'
import requests
response = requests.post(
"https://api.agent37.com/v1/instances",
headers={
"Authorization": "Bearer sk_live_...",
},
json={
"template": "agent37-hermes",
"resources": {
"cpu": 2,
"memory": 4,
"disk": 4,
},
"type": "default",
"user": "u_882",
"name": "Production agent",
"metadata": {
"plan": "pro",
},
"env": {
"APP_ENV": "production",
"LOG_LEVEL": "info",
},
"budget": {
"monthly_cap_micros": 5000000,
"credit_micros": 1000000,
},
"auto_sleep": True,
"idle_timeout_seconds": 900,
"public_ports": [
{
"port": 8080,
"prefix": "app",
"label": "My app",
},
],
},
)
response.raise_for_status()
print(response.json())
const response = await fetch(
"https://api.agent37.com/v1/instances",
{
method: "POST",
headers: {
Authorization: "Bearer sk_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
template: "agent37-hermes",
resources: {
cpu: 2,
memory: 4,
disk: 4,
},
type: "default",
user: "u_882",
name: "Production agent",
metadata: {
plan: "pro",
},
env: {
APP_ENV: "production",
LOG_LEVEL: "info",
},
budget: {
monthly_cap_micros: 5000000,
credit_micros: 1000000,
},
auto_sleep: true,
idle_timeout_seconds: 900,
public_ports: [
{
port: 8080,
prefix: "app",
label: "My app",
},
],
}),
},
);
if (!response.ok) {
throw new Error(await response.text());
}
console.log(await response.json());
{
"id": "ab12cd34ef",
"status": "running",
"url": "https://ab12cd34ef.agent37.app"
}
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 with402 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
| Error | When |
|---|---|
402 insufficient_balance | Create when the wallet holds less than one day of the instance’s running rate, or start of a past-due instance while the balance is negative. |
409 instance_limit_reached | Create when the workspace is at its instance cap, which counts every instance that is not deleted or failed, sleeping and stopped ones included: one instance on the free credit, 10 once topped up, 50 once top-ups total $100, 200 once they total $250 (email vishnu@agent37.com to raise it further). |
403 tier_limit | Create or resize asks for a shape larger than your plan includes. Free workspaces run any template on the 2 vCPU / 4 GB shape; a top-up unlocks the 4/8, 8/16, and 16/32 shapes. |
503 no_capacity | Create when no host has capacity for the requested shape right now. |
409 capacity_unavailable | Start or resize when no host in the fleet can fit the instance right now; the platform first tries to move it to a host with room. |