POST
Create a machine

Authorizations

x-api-key
string
header
required

Headers

x-bma-project-id
string

Project scope. Required when the API key can access more than one project (alias: anthropic-workspace-id).

Idempotency-Key
string

Replays the first result of a create; the same key with another body is 409.

Required string length: 1 - 255

Body

application/json

Agent machine (agent_id, persistent, template, ...), BYO connect (source byo, display_name, ...) or org machine (display_name, ...).

agent_id
string

The id /v1/agents uses; with persistent true and template, creates a persistent machine of that agent.

persistent
boolean

Must be true when agent_id is set.

template
string
machine_pool_id
string
display_name
string
source
enum<string>

byo connects a bring-your-own machine.

Available options:
byo
description
string
cwd
string
env
object
secret_env
object
metadata
object
project_ids
string[]
token_name
string

Response

Success.

An org machine, an agent machine (kind, machine_pool_name, cpu, memory_mb, agent_id) or a connected BYO machine (token); the fields of the other families are absent.

type
string
required
Allowed value: "machine"
id
string
required

Machine ID (mch_...).

Pattern: ^mch_[a-z2-7]{26}$
org_id
string
Pattern: ^org_[a-z2-7]{26}$
source_kind
enum<string>
Available options:
byo,
pool
machine_pool_id
string | null

Machine pool ID (mpo_...).

Pattern: ^mpo_[a-z2-7]{26}$
display_name
string

Human-readable name. Spaces and punctuation are allowed; leading or trailing whitespace and invisible or control characters are not.

Required string length: 1 - 64
description
string
provider
string
lifecycle_state
enum<string>
Available options:
provisioning,
provision_failed,
active,
deleting,
delete_failed,
deleted
connection_state
enum<string>
Available options:
online,
asleep,
offline
connection_state_reason
string
power_state
enum<string>

Compute state of a pool machine. paused keeps the disk (and memory when the provider supports it) without compute; resuming means a resume or restore is in flight; archived means the machine image is stored durably and is restored on the next access.

Available options:
running,
pausing,
paused,
resuming,
archiving,
archived
last_observed_at
string<date-time> | null
cwd
string
env
object
secret_env
object
lifecycle_reason_code
string
lifecycle_reason_message
string
failure_report
object

The machine's most recent daemon-reported failure. A single slot, overwritten by newer reports. Runtime crash reports remain as historical diagnostics; recovery may clear other failure stages.

next_reconcile_after
string<date-time> | null
provision_attempts
integer<int32>
delete_attempts
integer<int32>
metadata
object

Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters.

deleted_at
string<date-time> | null
created_at
string<date-time>
updated_at
string<date-time>
kind
enum<string>

Persistent machines are kept for a person and never deleted for being idle; ephemeral machines serve turns and are deleted after their idle window.

Available options:
persistent,
ephemeral
machine_pool_name
string

Human-readable name. Spaces and punctuation are allowed; leading or trailing whitespace and invisible or control characters are not.

Required string length: 1 - 64
cpu
integer<int32> | null

The machine shape BMA reports, or null before the provider resolves it.

Required range: x >= 1
memory_mb
integer<int32> | null

The machine shape BMA reports, or null before the provider resolves it.

Required range: x >= 1
agent_id
string

Agent machines only: the id /v1/agents uses .

capabilities
object | null

Single read only; null when the project cannot use the machine.

token
string

BYO connect only: the one-time machine token.

token_record
object
project_grants
object[]