POST /v1/capsules — Create a capsule

Use this endpoint to provision a new microVM capsule for your team. The capsule starts in pending status and transitions to starting, then running as the VM boots. All fields are optional — omit them to accept the defaults (minimal template, 1 vCPU, 512 MiB RAM, no auto-pause).

Endpoint

POST https://app.wrenn.dev/api/v1/capsules

Authentication

Pass your API key in the X-API-Key header. You can generate a key in the Wrenn dashboard.

X-API-Key: wrn_your_key

Request body

string

default:"minimal"

Name of the base template or snapshot template to boot from. Defaults to "minimal".

integer

default:"1"

Number of virtual CPUs to allocate to the capsule.

integer

default:"512"

Memory to allocate, in MiB.

integer

default:"0"

Inactivity TTL in seconds. The capsule is automatically paused after this many seconds with no exec calls or pings. Set to 0 to disable auto-pause.

Example request body

{
  "template": "base-python",
  "vcpus": 2,
  "memory_mb": 1024,
  "timeout_sec": 300
}

Response

Returns a 201 Created with the capsule object.

string

required

Unique capsule ID. Always prefixed with cl- (e.g., "cl-abc123").

string

required

Current lifecycle status. One of: pending, starting, running, paused, stopped, error.

string

required

Name of the template used to create the capsule.

integer

required

Number of virtual CPUs allocated.

integer

required

Memory allocated, in MiB.

integer

required

Inactivity TTL in seconds. 0 means auto-pause is disabled.

string

required

ISO 8601 timestamp of when the capsule was created.

string

required

ISO 8601 timestamp of the most recent status change.

string

ISO 8601 timestamp of when the capsule last reached running status. null until the VM has booted at least once.

string

ISO 8601 timestamp of the last exec call or ping. Used to calculate the auto-pause TTL.

Example response

{
  "id": "cl-abc123",
  "status": "starting",
  "template": "base-python",
  "vcpus": 2,
  "memory_mb": 1024,
  "timeout_sec": 300,
  "created_at": "2024-11-01T10:00:00Z",
  "started_at": null,
  "last_active_at": null,
  "last_updated": "2024-11-01T10:00:00Z"
}

curl

curl --request POST \
  --url https://app.wrenn.dev/api/v1/capsules \
  --header 'X-API-Key: wrn_your_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "template": "base-python",
    "vcpus": 2,
    "memory_mb": 1024,
    "timeout_sec": 300
  }'

Python SDK

from wrenn import Capsule

capsule = Capsule(
    template="base-python",
    vcpus=2,
    memory_mb=1024,
    timeout=300,
    wait=True,  # block until status is "running"
)
print(capsule.id)      # "cl-abc123"
print(capsule.status)  # "running"

Pass wait=True to block until the capsule reaches running status before your code continues. Without it, status will be "pending" or "starting" immediately after the call.

Error responses

Status	Code	Description
`401 Unauthorized`	—	Missing or invalid `X-API-Key`.
`502 Bad Gateway`	—	The host agent returned an error while provisioning the VM. Retry after a short delay.

Capsules

Execution

Files

Snapshots

POST /v1/capsules — Create a capsule

Endpoint

Authentication

Request body

Example request body

Response

Example response

curl

Python SDK

Error responses

​Endpoint

​Authentication

​Request body

​Example request body

​Response

​Example response

​curl

​Python SDK

​Error responses

Endpoint

Authentication

Request body

Example request body

Response

Example response

curl

Python SDK

Error responses