POST/v1/fork

Create a VM, either from an OCI image or by forking an existing VM.

Request

Specify exactly one of image, source_vm_id, or source_vm_name. If image is present it takes precedence over the other two.

image

String

Required, one of

OCI image reference, e.g. ubuntu:24.04. Boots a rootfs converted from the image.

source_vm_id

String

Required, one of

Id of an existing VM to fork from.

source_vm_name

String

Required, one of

Name of an existing VM to fork from.

name

String

Name for the new VM.

resources

Object

{ "vcpu": 2, "memory_mib": 2048, "disk_mib": 10240 } is the default; any field you omit falls back to it.

registry_auth

Object

Credentials for pulling image from a private registry (ghcr.io, a private Docker Hub repo, ECR, etc): { "username": "...", "password": "..." }. Used only for this one pull and never stored. For AWS ECR use username AWS with the output of aws ecr get-login-password; for Docker Hub or GHCR use your username and a personal access token as the password. Ignored when forking from a source VM, which has no registry to authenticate against.

Response

Returns a VM object for the new machine.

Example

Fork from an image:

bash

curl -X POST localhost:7240/v1/fork \
  -H "Content-Type: application/json" \
  -d '{"image":"ubuntu:24.04"}'

Fork from a running VM:

bash

curl -X POST localhost:7240/v1/fork \
  -H "Content-Type: application/json" \
  -d "{\"source_vm_id\":\"$VM\",\"name\":\"feature-xyz\"}"

Fork from a private image:

bash

curl -X POST localhost:7240/v1/fork \
  -H "Content-Type: application/json" \
  -d '{
    "image": "ghcr.io/org/private-image:latest",
    "registry_auth": { "username": "myuser", "password": "$GHCR_TOKEN" }
  }'