Skip to main content
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

​
template
string
default:"minimal"
Name of the base template or snapshot template to boot from. Defaults to "minimal".
​
vcpus
integer
default:"1"
Number of virtual CPUs to allocate to the capsule.
​
memory_mb
integer
default:"512"
Memory to allocate, in MiB.
​
timeout_sec
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.
​
id
string
required
Unique capsule ID. Always prefixed with cl- (e.g., "cl-abc123").
​
status
string
required
Current lifecycle status. One of: pending, starting, running, paused, stopped, error.
​
template
string
required
Name of the template used to create the capsule.
​
vcpus
integer
required
Number of virtual CPUs allocated.
​
memory_mb
integer
required
Memory allocated, in MiB.
​
timeout_sec
integer
required
Inactivity TTL in seconds. 0 means auto-pause is disabled.
​
created_at
string
required
ISO 8601 timestamp of when the capsule was created.
​
last_updated
string
required
ISO 8601 timestamp of the most recent status change.
​
started_at
string
ISO 8601 timestamp of when the capsule last reached running status. null until the VM has booted at least once.
​
last_active_at
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

StatusCodeDescription
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.