---
title: "Create and start instance"
method: POST
path: "/instances"
---

# Create and start instance

`POST /instances`

## Request body

- CreateInstanceRequest
  - `name` string, required — Human-readable name (lowercase letters, digits, and dashes only; cannot start or end with a dash)
  - `image` string, required — OCI image reference
  - `platform` string — Target platform as os/arch[/variant] (e.g. "linux/amd64"), matching Docker --platform. Omit for the host platform. Not a fixed enum: the os/arch[/variant] grammar is validated server-side and invalid values return 400 invalid_platform. Only os "linux" with arch amd64 or arm64 is accepted today.
  - `size` string — Base memory size (human-readable format like "1GB", "512MB", "2G")
  - `hotplug_size` string — Additional memory for hotplug (human-readable format like "3GB", "1G"). Omit to disable hotplug memory.
  - `overlay_size` string — Writable overlay disk size (human-readable format like "10GB", "50G")
  - `disk_io_bps` string — Disk I/O rate limit (e.g., "100MB/s", "500MB/s"). Defaults to proportional share based on CPU allocation if configured.
  - `vcpus` integer — Number of virtual CPUs
  - `env` object — Environment variables
  - `credentials` object — 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.
  - `tags` Tags — User-defined key-value tags.
  - `network` object — Network configuration for the instance
    - `enabled` boolean — Whether to attach instance to the default network
    - `bandwidth_download` string — Download bandwidth limit (external→VM, e.g., "1Gbps", "125MB/s"). Defaults to proportional share based on CPU allocation.
    - `bandwidth_upload` string — Upload bandwidth limit (VM→external, e.g., "1Gbps", "125MB/s"). Defaults to proportional share based on CPU allocation.
    - `egress` CreateInstanceRequestNetworkEgress — Host-mediated outbound network policy. Omit this object, or set `enabled: false`, to preserve normal direct outbound networking when `network.enabled` is true.
      - `enabled` boolean — Whether to enable the mediated egress path. When false or omitted, the instance keeps normal direct outbound networking and host-managed credential rewriting is disabled.
      - `enforcement` CreateInstanceRequestNetworkEgressEnforcement — Egress enforcement policy applied when mediation is enabled.
        - `mode` 'all' | 'http_https_only' — `all` (default) rejects direct non-mediated TCP egress from the VM, while `http_https_only` rejects direct egress only on TCP ports 80 and 443.
  - `devices` string[] — Device IDs or names to attach for GPU/PCI passthrough
  - `gpu` GPUConfig — GPU configuration for the instance
    - `profile` string — vGPU profile name (e.g., "L40S-1Q"). Only used in vGPU mode.
  - `volumes` VolumeMount[] — Volumes to attach to the instance at creation time
    - `volume_id` string, required — Volume identifier
    - `mount_path` string, required — Path where volume is mounted in the guest
    - `readonly` boolean — Whether volume is mounted read-only
    - `overlay` boolean — Create per-instance overlay for writes (requires readonly=true)
    - `overlay_size` string — Max overlay size as human-readable string (e.g., "1GB"). Required if overlay=true.
  - `hypervisor` 'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz' — Hypervisor to use for this instance. Defaults to server configuration.
  - `snapshot_policy` SnapshotPolicy
    - `compression` SnapshotCompressionConfig
      - `enabled` boolean, required — Enable snapshot memory compression
      - `algorithm` 'zstd' | 'lz4' — Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
      - `level` integer — Compression level. Allowed ranges are zstd=1-19 and lz4=0-9. When omitted, zstd defaults to 1 and lz4 defaults to 0. Ignored when enabled is false.
    - `standby_compression_delay` string — Delay before standby snapshot compression begins, expressed as a Go duration like "30s" or "5m". Applies only to standby compression and defaults to immediate start when omitted.
  - `auto_standby` AutoStandbyPolicy — Linux-only automatic standby policy based on active inbound TCP connections observed from the host conntrack table.
    - `enabled` boolean — Whether automatic standby is enabled for this instance.
    - `idle_timeout` string — How long the instance must have zero qualifying inbound TCP connections before Hypeman places it into standby.
    - `ignore_source_cidrs` string[] — Optional client CIDRs that should not keep the instance awake.
    - `ignore_destination_ports` integer[] — Optional destination TCP ports that should not keep the instance awake.
  - `health_check` HealthCheck — Workload health check policy. Health is reported separately from instance lifecycle state.
    - `type` 'none' | 'http' | 'tcp' | 'exec' — Probe type. Omit health_check or set type=none to disable health checks.
    - `interval` string — Delay between checks as a Go duration.
    - `timeout` string — Per-check timeout as a Go duration.
    - `start_period` string — Startup grace period before failures can mark the workload unhealthy.
    - `failure_threshold` integer — Consecutive failed checks required to mark the workload unhealthy.
    - `success_threshold` integer — Consecutive successful checks required to mark the workload healthy.
    - `http` HealthCheckHTTP
      - `port` integer, required — Port to probe on the instance network address.
      - `path` string — HTTP path to request.
      - `scheme` 'http' | 'https' — HTTP scheme to use for the probe.
      - `expected_status` integer — Exact status code required for a successful probe.
    - `tcp` HealthCheckTCP
      - `port` integer, required — Port to open on the instance network address.
    - `exec` HealthCheckExec
      - `command` string[], required — Command and arguments to run inside the guest after guest-agent readiness.
      - `working_dir` string — Optional working directory for the command.
  - `restart_policy` RestartPolicy — Whole-instance restart supervision policy.
    - `policy` 'never' | 'always' | 'on_failure' — Restart behavior when the guest program exits: - never: do not automatically restart - always: restart after any guest exit - on_failure: restart only for nonzero, signaled, OOM, or unknown exits
    - `backoff` string — Delay before each restart attempt, expressed as a Go duration like "5s" or "1m".
    - `max_attempts` integer — Consecutive automatic restart attempts before blocking retries. 0 means unlimited.
    - `stable_after` string — Running this long resets the consecutive restart attempt count.
  - `skip_kernel_headers` boolean — 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_agent` boolean — 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.
  - `entrypoint` string[] — Override image entrypoint (like docker run --entrypoint). Omit to use image default.
  - `cmd` string[] — Override image CMD (like docker run <image> <command>). Omit to use image default.

## Response `201`

Instance created

- Instance
  - `id` string, required — Auto-generated unique identifier (CUID2 format)
  - `name` string, required — Human-readable name
  - `image` string, required — OCI image reference
  - `platform` string — 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_error` string, nullable — Error message if state couldn't be determined (only set when state is Unknown)
  - `size` string — Base memory size (human-readable)
  - `hotplug_size` string — Hotplug memory size (human-readable)
  - `overlay_size` string — Writable overlay disk size (human-readable)
  - `vcpus` integer — Number of virtual CPUs
  - `disk_io_bps` string — Disk I/O rate limit (human-readable, e.g., "100MB/s")
  - `env` object — Environment variables
  - `tags` Tags — User-defined key-value tags.
  - `network` object — Network configuration of the instance
    - `enabled` boolean — Whether instance is attached to the default network
    - `name` string — Network name (always "default" when enabled)
    - `ip` string, nullable — Assigned IP address (null if no network)
    - `mac` string, nullable — Assigned MAC address (null if no network)
    - `bandwidth_download` string — Download bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
    - `bandwidth_upload` string — Upload bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
  - `volumes` VolumeMount[] — Volumes attached to the instance
    - `volume_id` string, required — Volume identifier
    - `mount_path` string, required — Path where volume is mounted in the guest
    - `readonly` boolean — Whether volume is mounted read-only
    - `overlay` boolean — Create per-instance overlay for writes (requires readonly=true)
    - `overlay_size` string — Max overlay size as human-readable string (e.g., "1GB"). Required if overlay=true.
  - `gpu` InstanceGPU — GPU information attached to the instance
    - `profile` string — vGPU profile name
    - `mdev_uuid` string — mdev device UUID
  - `created_at` string, date-time, required — Creation timestamp (RFC3339)
  - `started_at` string, date-time, nullable — Start timestamp (RFC3339)
  - `stopped_at` string, date-time, nullable — Stop timestamp (RFC3339)
  - `exit_code` integer, nullable — App exit code (null if VM hasn't exited)
  - `exit_message` string — Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")
  - `has_snapshot` boolean — Whether a snapshot exists for this instance
  - `hypervisor` 'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz' — Hypervisor running this instance
  - `snapshot_policy` SnapshotPolicy
    - `compression` SnapshotCompressionConfig
      - `enabled` boolean, required — Enable snapshot memory compression
      - `algorithm` 'zstd' | 'lz4' — Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
      - `level` integer — Compression level. Allowed ranges are zstd=1-19 and lz4=0-9. When omitted, zstd defaults to 1 and lz4 defaults to 0. Ignored when enabled is false.
    - `standby_compression_delay` string — Delay before standby snapshot compression begins, expressed as a Go duration like "30s" or "5m". Applies only to standby compression and defaults to immediate start when omitted.
  - `auto_standby` AutoStandbyPolicy — Linux-only automatic standby policy based on active inbound TCP connections observed from the host conntrack table.
    - `enabled` boolean — Whether automatic standby is enabled for this instance.
    - `idle_timeout` string — How long the instance must have zero qualifying inbound TCP connections before Hypeman places it into standby.
    - `ignore_source_cidrs` string[] — Optional client CIDRs that should not keep the instance awake.
    - `ignore_destination_ports` integer[] — Optional destination TCP ports that should not keep the instance awake.
  - `health_check` HealthCheck — Workload health check policy. Health is reported separately from instance lifecycle state.
    - `type` 'none' | 'http' | 'tcp' | 'exec' — Probe type. Omit health_check or set type=none to disable health checks.
    - `interval` string — Delay between checks as a Go duration.
    - `timeout` string — Per-check timeout as a Go duration.
    - `start_period` string — Startup grace period before failures can mark the workload unhealthy.
    - `failure_threshold` integer — Consecutive failed checks required to mark the workload unhealthy.
    - `success_threshold` integer — Consecutive successful checks required to mark the workload healthy.
    - `http` HealthCheckHTTP
      - `port` integer, required — Port to probe on the instance network address.
      - `path` string — HTTP path to request.
      - `scheme` 'http' | 'https' — HTTP scheme to use for the probe.
      - `expected_status` integer — Exact status code required for a successful probe.
    - `tcp` HealthCheckTCP
      - `port` integer, required — Port to open on the instance network address.
    - `exec` HealthCheckExec
      - `command` string[], required — Command and arguments to run inside the guest after guest-agent readiness.
      - `working_dir` string — Optional working directory for the command.
  - `health_status` InstanceHealthStatus
    - `status` 'disabled' | 'starting' | 'healthy' | 'unhealthy' | 'unknown', required — Current workload health status.
    - `consecutive_successes` integer, required — Consecutive successful checks in the current health window.
    - `consecutive_failures` integer, required — Consecutive failed checks in the current health window.
    - `last_checked_at` string, date-time, nullable — Most recent check completion time.
    - `last_success_at` string, date-time, nullable — Most recent successful check completion time.
    - `last_failure_at` string, date-time, nullable — Most recent failed check completion time.
    - `last_error` string, nullable — Truncated error from the most recent failed check.
  - `restart_policy` RestartPolicy — Whole-instance restart supervision policy.
    - `policy` 'never' | 'always' | 'on_failure' — Restart behavior when the guest program exits: - never: do not automatically restart - always: restart after any guest exit - on_failure: restart only for nonzero, signaled, OOM, or unknown exits
    - `backoff` string — Delay before each restart attempt, expressed as a Go duration like "5s" or "1m".
    - `max_attempts` integer — Consecutive automatic restart attempts before blocking retries. 0 means unlimited.
    - `stable_after` string — Running this long resets the consecutive restart attempt count.
  - `restart_status` RestartStatus — Runtime status for restart policy decisions.
    - `attempts` integer — Consecutive automatic restart attempts in the current failure window.
    - `last_attempt_at` string, date-time, nullable — Last time Hypeman attempted an automatic restart.
    - `next_attempt_at` string, date-time, nullable — Next scheduled automatic restart attempt after backoff.
    - `blocked_reason` 'manual_stop' | 'max_attempts_exceeded', nullable — Reason automatic restarts are currently blocked.
    - `last_reason` 'health_check_failed', nullable — Most recent non-exit failure signal that entered restart policy.
  - `phase_durations_ms` object — 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_phase` string — The lifecycle phase the instance is currently in.
  - `current_phase_since` string, date-time — When the instance entered current_phase.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Image not found or requested platform not available
- `409` — Conflict - insufficient resources or name already exists
- `429` — Registry rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.net/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kernel/hypeman-api/versions/b4642bb950dc/schema)