API Reference

Betawings REST API — v1

The Betawings API lets you orchestrate Firecracker MicroVMs. VMs boot in under a second from a snapshot and are isolated at the hardware-virtualisation level — more secure than containers, more efficient than traditional VMs.

All endpoints return JSON. Error responses always include an error field.

Base URL

Response format

All successful responses are application/json. Errors use standard HTTP status codes with a JSON body:

{"error": "vm must be stopped before resizing cpu/memory"}

Authentication

Every request to /api/v1/* must include a bearer token in the Authorization header.

Authorization: Bearer <your-token>

Roles

Three org-scoped built-in roles are currently available to users.

Creating a token

curl -X POST https://api.betawings.com/api/v1/tokens/ \
  -H "Authorization: Bearer <org-admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy","role":"creator","org_id":"<org-id>"}'

The raw token is only returned once at creation time — store it immediately.

The VM Object

VM lifecycle

Create VM

Creates a new VM and starts it immediately. The VM is provisioned from the specified base image. If multi-node is configured, the CP auto-selects the node with the most free memory unless node_id is specified.

When targeting a remote node, provisioning is asynchronous — the API returns immediately with status: "deploying". Poll Get VM until status becomes "stopped" or "error".

Request body

curl -X POST https://api.betawings.com/api/v1/vms/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "image": "demo-44322",
    "cpus": 1,
    "memory_mb": 512,
    "ssh_public_key": "ssh-ed25519 AAAA... you@host",
    "idle_timeout_seconds": 600
  }'

{
  "id":                  "3f9a1c2b4e5d6f7a",
  "name":                "my-project",
  "status":              "running",
  "image":               "demo-44322",
  "cpu_count":           1,
  "memory_mb":           512,
  "disk_mb":             4096,
  "ip_address":          "10.200.3.2",
  "idle_timeout_seconds":600,
  "has_snapshot":        false,
  "ssh_key_fingerprint": "SHA256:abc123...",
  "terminal_url":        "https://my-project.onbw.net/terminal/<token>/",
  "node_id":             "local",
  "created_at":          "2026-07-11T10:00:00Z",
  "started_at":          "2026-07-11T10:00:01Z"
}

List VMs

Returns all VMs the caller can access. Org-scoped callers see only their org's VMs; cloud-admin sees all.

Query parameters

curl https://api.betawings.com/api/v1/vms/?status=running \
  -H "Authorization: Bearer $TOKEN"

Get VM

Returns a single VM by ID.

curl https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a \
  -H "Authorization: Bearer $TOKEN"

Resize & Rename VM

Updates one or more mutable VM properties. All fields are optional — include only what you want to change.

curl -X PATCH https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cpus": 2, "memory_mb": 1024, "tags": {"env": "prod"}}'

Start VM

Starts a stopped VM. If a Firecracker snapshot exists (has_snapshot: true), the VM resumes from it in ~1 second. Otherwise it cold-boots (~10–20 seconds). Returns the updated VM object.

curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/start \
  -H "Authorization: Bearer $TOKEN"

Stop VM

Stops a running VM. The Firecracker process is sent SIGKILL. Any unsaved in-memory state is lost; the disk (rootfs.ext4) is fully preserved.

curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/stop \
  -H "Authorization: Bearer $TOKEN"

Snapshot VM

Creates a Firecracker memory snapshot of a running VM. The next start will restore from this snapshot (~1 s) rather than cold-booting. By default the VM is stopped after the snapshot; pass keep_running: true to leave it running (useful for periodic checkpoints).

curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/snapshot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keep_running": true}'

Rebuild VM

Replaces the VM's disk with a fresh copy of its base image. All data on the disk is permanently erased. The VM must be stopped. Any existing snapshot is cleared.

curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/rebuild \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ssh_public_key": "ssh-ed25519 AAAA... you@host"}'

Migrate VM

Moves a VM's disk to a different node. The VM's rootfs.ext4 is streamed from the source host through the CP to the target host. After migration the VM can be started on the new host with a cold boot.

The VM must be stopped before migrating. The operation is crash-safe: the DB node_id is only updated after the target has received the full rootfs.

# Move a local VM onto a remote node
curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/migrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_node_id": "8d82890e3c0fb5aa"}'

# Pull a VM from a remote node back to local
curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/migrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_node_id": "local"}'

Destroy VM

Permanently deletes a VM — the Firecracker process, disk image, snapshots, and DB record are all removed. This cannot be undone.

Returns 204 No Content on success.

curl -X DELETE https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a \
  -H "Authorization: Bearer $TOKEN"

Set Idle Config

Updates the VM's idle timeout. When the VM has had no activity for this many seconds, the idle checker automatically creates a Firecracker memory snapshot and stops the VM — freeing its CPU and RAM. The next incoming HTTPS, SSH, or HTTP request to the VM's domain triggers an automatic resume from snapshot (~300 ms).

What counts as activity: any proxied connection through the Betawings gateway (HTTPS, SSH, HTTP), or an explicit Report Activity call from inside the VM. The timer resets on each event.

curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/idle-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idle_timeout_seconds": 1800}'

Get Activity Info

Returns how long the VM has been idle and when it will be shut down by the idle checker.

curl https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/activity \
  -H "Authorization: Bearer $TOKEN"

{
  "last_activity_at":      "2026-07-11T10:05:00Z",
  "idle_for_seconds":      120,
  "will_shutdown_in_seconds": 180
}

Report Activity

Resets the idle timer, signalling that the VM is still in use. Call this from inside the VM (or from a client) when work is happening, to prevent an idle shutdown. The source field is informational only.

curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/activity \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "user-request", "packet_count": 42}'

Get VM Logs

Returns the last N lines of the VM's Firecracker log. The log contains kernel boot messages, device initialisation output, and any text written by the guest to the serial console. Useful for diagnosing boot failures and startup scripts.

curl "https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/logs?lines=200" \
  -H "Authorization: Bearer $TOKEN"

Overview

Betawings uses SSH ProxyJump: your SSH client connects to the gateway at api.betawings.com:2222, which resolves the target VM by name and forwards the connection directly. The gateway never terminates or inspects the SSH session.

Connect directly without a config file using the -J ProxyJump flag:

ssh -J root@api.betawings.com:2222 root@my-project.onbw.net

SSH Config

Add the following block to ~/.ssh/config for seamless access to all your VMs:

# Wings gateway
Host wings-gw
  HostName api.betawings.com
  Port 2222
  User root
  IdentityFile ~/.ssh/your-key

# All VMs on *.onbw.net jump through the gateway
Host *.onbw.net
  User root
  ProxyJump wings-gw
  IdentityFile ~/.ssh/your-key

Once configured, connect with just:

ssh my-project.onbw.net

The hostname my-project must match the name field of your VM exactly.

Wake on SSH

If the VM is currently sleeping (stopped with a snapshot), the SSH proxy automatically wakes it before forwarding the connection. Your SSH client holds the TCP connection open while the VM resumes from snapshot — typically under 300 ms. No retry is needed on the client side.

List Domains

curl https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/domains \
  -H "Authorization: Bearer $TOKEN"

Add Domain

Registers a custom domain for a VM and returns a DNS challenge value. The domain is not yet verified — create the TXT record and call Verify.

curl -X PUT https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/domains/myapp.example.com \
  -H "Authorization: Bearer $TOKEN"

{
  "domain":      "myapp.example.com",
  "vm_id":       "3f9a1c2b4e5d6f7a",
  "status":      "pending_verification",
  "txt_record":  "_wings-challenge.myapp.example.com",
  "txt_value":   "wings-a1b2c3d4...",
  "verify_hint": "Set TXT record, then POST /api/v1/vms/.../domains/.../verify"
}

Verify Domain

Checks that the DNS TXT record _wings-challenge.{domain} contains the challenge value issued by Add Domain. On success the domain is marked verified and Wings begins routing it to the VM.

curl -X POST https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/domains/myapp.example.com/verify \
  -H "Authorization: Bearer $TOKEN"

Remove Domain

Removes the custom domain association. Wings stops routing that domain to the VM. Returns 204 No Content.

curl -X DELETE https://api.betawings.com/api/v1/vms/3f9a1c2b4e5d6f7a/domains/myapp.example.com \
  -H "Authorization: Bearer $TOKEN"

Create Token

Creates a new API token. The raw token value is returned once — it is not stored and cannot be retrieved later. Store it securely immediately.

curl -X POST https://api.betawings.com/api/v1/tokens/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "role": "creator",
    "org_id": "a1b2c3d4e5f6",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

{
  "token":      "bwt_a1b2c3...<only shown once>",
  "id":         "7c8d9e0f1a2b",
  "name":       "ci-pipeline",
  "role":       "creator",
  "org_id":     "a1b2c3d4e5f6",
  "scope_type": "org",
  "created_at": "2026-07-11T10:00:00Z"
}

List Tokens

Returns all tokens visible to the caller. Cloud-admin sees all tokens; org-scoped callers see only tokens belonging to their org. Raw token values are never returned.

curl https://api.betawings.com/api/v1/tokens/ \
  -H "Authorization: Bearer $TOKEN"

Delete Token

Revokes a token immediately. All subsequent requests using that token receive 401 Unauthorized. Returns 204 No Content.

curl -X DELETE https://api.betawings.com/api/v1/tokens/7c8d9e0f1a2b \
  -H "Authorization: Bearer $TOKEN"

Health Check

No authentication required. Returns platform health and VM counts. Use this for uptime monitoring.

curl https://api.betawings.com/health

{
  "status":      "ok",
  "vms_running": 4,
  "vms_stopped": 12,
  "vms_total":   16
}

List Images

Returns available base disk images. The name field is what you pass as image when creating a VM.

curl https://api.betawings.com/api/v1/images \
  -H "Authorization: Bearer $TOKEN"

[{
  "name":       "demo-44322",
  "size_bytes": 4294967296
}]