KEkernel

Create and start instance

Changed on
post/instances

Request

  • Base URL
    http://localhost:4973
  • URL
    http://localhost:4973/instances
  • Auth
    HTTP bearer

Request body

namestring required

Human-readable name (lowercase letters, digits, and dashes only; cannot start or end with a dash)

imagestring required

OCI image reference

platformstring

Target platform as os/arch[/variant]. Linux container guests support amd64 and arm64. Experimental darwin/arm64 guests require an offline-imported macOS disk image and vz on Apple silicon. Omit to use the cached native image or host platform.

sizestring

Base memory size (human-readable format like "1GB", "512MB", "2G"). macOS guests default to their image's memory; explicit sizes must be at least 4 GiB in whole MiB and within VZ host limits.

hotplug_sizestring

Additional memory for hotplug (human-readable format like "3GB", "1G"). Omit to disable hotplug memory.

overlay_sizestring

Writable overlay disk size (human-readable format like "10GB", "50G"). Omit this field for macOS guests, which clone the image's complete boot disk instead.

disk_io_bpsstring

Disk I/O rate limit (e.g., "100MB/s", "500MB/s"). Defaults to proportional share based on CPU allocation if configured.

vcpusinteger

Number of virtual CPUs. macOS guests default to their image's vCPUs; explicit counts must be at least 2 and within VZ host limits.

envobject

Environment variables

credentialsobject

Host-managed credential brokering policies keyed by guest-visible env var name. Those guest env vars receive mock placeholder values, while the real values remain host-scoped in the request env map and are only materialized on the mediated egress path according to each credential's source and inject rules.

tagsTags

User-defined key-value tags.

ttlstring

Relative lifetime from instance creation, in Go duration format. Use "0s" or omit both expiration fields to disable automatic expiration. Mutually exclusive with expires_at.

expires_atstring date-time

Absolute expiration time. Must be in the future and is mutually exclusive with ttl.

devicesstring[]

Device IDs or names to attach for GPU/PCI passthrough

hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'qemu-microvm' | 'vz'

Hypervisor backend to use for this instance. qemu uses the architecture-native standard board; qemu-microvm uses QEMU's minimal Linux amd64 board and does not support PCI devices, hotplug memory, or more than eight virtio-mmio devices. Defaults to server configuration.

skip_kernel_headersboolean

Skip kernel headers installation during boot for faster startup. When true, DKMS (Dynamic Kernel Module Support) will not work, preventing compilation of out-of-tree kernel modules (e.g., NVIDIA vGPU drivers). Recommended for workloads that don't need kernel module compilation.

skip_guest_agentboolean

Skip guest-agent installation during boot. When true, the exec and stat APIs will not work for this instance. The instance will still run, but remote command execution will be unavailable.

entrypointstring[]

Override image entrypoint (like docker run --entrypoint). Omit to use image default.

cmdstring[]

Override image CMD (like docker run <image> <command>). Omit to use image default.

Example request

{
  "name": "my-workload-1",
  "image": "docker.io/library/alpine:latest",
  "platform": "linux/amd64",
  "size": "2GB",
  "hotplug_size": "2GB",
  "overlay_size": "20GB",
  "disk_io_bps": "100MB/s",
  "vcpus": 2,
  "env": {
    "PORT": "3000",
    "NODE_ENV": "production"
  },
  "credentials": {
    "OUTBOUND_OPENAI_KEY": {
      "source": {
        "env": "OUTBOUND_OPENAI_KEY"
      },
      "inject": [
        {
          "hosts": [
            "api.openai.com",
            "*.openai.com"
          ],
          "as": {
            "header": "Authorization",
            "format": "Bearer ${value}"
          }
        }
      ]
    }
  },
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "ttl": "24h",
  "expires_at": "2026-08-21T18:00:00Z",
  "network": {
    "enabled": true,
    "bandwidth_download": "1Gbps",
    "bandwidth_upload": "1Gbps",
    "egress": {
      "enabled": true,
      "enforcement": {
        "mode": "all"
      }
    }
  },
  "devices": [
    "l4-gpu"
  ],
  "gpu": {
    "profile": "L40S-1Q"
  },
  "volumes": [
    {
      "volume_id": "vol-abc123",
      "mount_path": "/mnt/data",
      "overlay_size": "1GB"
    }
  ],
  "hypervisor": "cloud-hypervisor",
  "snapshot_policy": {
    "compression": {
      "enabled": true,
      "algorithm": "zstd",
      "level": 1
    },
    "standby_compression_delay": "2m"
  },
  "auto_standby": {
    "enabled": true,
    "idle_timeout": "5m",
    "ignore_source_cidrs": [
      "10.0.0.0/8",
      "192.168.0.0/16"
    ],
    "ignore_destination_ports": [
      22,
      9000
    ]
  },
  "health_check": {
    "interval": "10s",
    "timeout": "2s",
    "start_period": "30s",
    "failure_threshold": 3,
    "success_threshold": 1,
    "http": {
      "port": 8080,
      "path": "/healthz",
      "scheme": "http",
      "expected_status": 200
    },
    "tcp": {
      "port": 5432
    },
    "exec": {
      "command": [
        "curl",
        "-f",
        "http://localhost:4318/"
      ],
      "working_dir": "/app"
    }
  },
  "restart_policy": {
    "policy": "on_failure",
    "backoff": "5s",
    "max_attempts": 10,
    "stable_after": "10m"
  },
  "skip_kernel_headers": true,
  "entrypoint": [
    "/bin/sh",
    "-c"
  ],
  "cmd": [
    "echo",
    "hello"
  ]
}

Response

Instance created

idstring required

Auto-generated unique identifier (CUID2 format)

namestring required

Human-readable name

imagestring required

OCI image reference

platformstring

Resolved image platform as os/arch[/variant] (e.g. "linux/amd64"). amd64 images on an arm64 host run under Rosetta emulation.

state'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown' required

Instance state:

  • Created: VMM created but not started (Cloud Hypervisor native)
  • Initializing: VM is running while guest init is still in progress
  • Running: Guest program has started and instance is ready
  • Paused: VM is paused (Cloud Hypervisor native)
  • Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
  • Stopped: No VMM running, no snapshot exists
  • Standby: No VMM running, snapshot exists (can be restored)
  • Unknown: Failed to determine state (see state_error for details)
state_errorstring nullable

Error message if state couldn't be determined (only set when state is Unknown)

sizestring

Base memory size (human-readable)

hotplug_sizestring

Hotplug memory size (human-readable)

overlay_sizestring

Writable overlay disk size (human-readable)

vcpusinteger

Number of virtual CPUs

disk_io_bpsstring

Disk I/O rate limit (human-readable, e.g., "100MB/s")

envobject

Environment variables

tagsTags

User-defined key-value tags.

created_atstring date-time required

Creation timestamp (RFC3339)

expires_atstring date-time nullable required

Absolute expiration time, or null when automatic expiration is disabled. Instance TTL is cleared on fork.

started_atstring date-time nullable

Start timestamp (RFC3339)

stopped_atstring date-time nullable

Stop timestamp (RFC3339)

exit_codeinteger nullable

App exit code (null if VM hasn't exited)

exit_messagestring

Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")

has_snapshotboolean

Whether a snapshot exists for this instance

hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'qemu-microvm' | 'vz'

Hypervisor backend running this instance

phase_durations_msobject

Cumulative milliseconds the instance has spent in each lifecycle phase, including time accrued in the current phase up to the response time. Keys mirror instance states lowercased (running, standby, paused, stopped, created, initializing, shutdown). Consumers (e.g. billing) sum the phases they consider billable.

current_phasestring

The lifecycle phase the instance is currently in.

current_phase_sincestring date-time

When the instance entered current_phase.

Example response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "name": "my-workload-1",
  "image": "docker.io/library/alpine:latest",
  "platform": "linux/amd64",
  "state_error": "failed to query VMM: connection refused",
  "size": "2GB",
  "hotplug_size": "2GB",
  "overlay_size": "10GB",
  "vcpus": 2,
  "disk_io_bps": "100MB/s",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "network": {
    "enabled": true,
    "name": "default",
    "ip": "192.168.100.10",
    "mac": "02:00:00:ab:cd:ef",
    "bandwidth_download": "125MB/s",
    "bandwidth_upload": "125MB/s"
  },
  "volumes": [
    {
      "volume_id": "vol-abc123",
      "mount_path": "/mnt/data",
      "overlay_size": "1GB"
    }
  ],
  "gpu": {
    "profile": "L40S-1Q",
    "mdev_uuid": "aa618089-8b16-4d01-a136-25a0f3c73123",
    "device_path": "/sys/bus/pci/devices/0000:82:00.4"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2026-08-21T18:00:00Z",
  "started_at": "2025-01-15T10:30:05Z",
  "stopped_at": "2025-01-15T12:30:00Z",
  "exit_code": 137,
  "exit_message": "killed by signal 9 (SIGKILL)",
  "hypervisor": "cloud-hypervisor",
  "snapshot_policy": {
    "compression": {
      "enabled": true,
      "algorithm": "zstd",
      "level": 1
    },
    "standby_compression_delay": "2m"
  },
  "auto_standby": {
    "enabled": true,
    "idle_timeout": "5m",
    "ignore_source_cidrs": [
      "10.0.0.0/8",
      "192.168.0.0/16"
    ],
    "ignore_destination_ports": [
      22,
      9000
    ]
  },
  "health_check": {
    "interval": "10s",
    "timeout": "2s",
    "start_period": "30s",
    "failure_threshold": 3,
    "success_threshold": 1,
    "http": {
      "port": 8080,
      "path": "/healthz",
      "scheme": "http",
      "expected_status": 200
    },
    "tcp": {
      "port": 5432
    },
    "exec": {
      "command": [
        "curl",
        "-f",
        "http://localhost:4318/"
      ],
      "working_dir": "/app"
    }
  },
  "health_status": {
    "status": "healthy",
    "consecutive_successes": 4,
    "last_checked_at": "2026-05-16T01:00:00Z",
    "last_success_at": "2026-05-16T01:00:00Z",
    "last_failure_at": "2026-05-16T00:59:50Z",
    "last_error": "connection refused"
  },
  "restart_policy": {
    "policy": "on_failure",
    "backoff": "5s",
    "max_attempts": 10,
    "stable_after": "10m"
  },
  "restart_status": {
    "attempts": 3,
    "last_attempt_at": "2025-01-15T12:30:00Z",
    "next_attempt_at": "2025-01-15T12:30:05Z",
    "blocked_reason": "max_attempts_exceeded",
    "last_reason": "health_check_failed"
  },
  "phase_durations_ms": {
    "running": 60000,
    "standby": 300000
  },
  "current_phase": "running",
  "current_phase_since": "2026-05-11T14:00:00Z"
}

Changes