---
title: "Attach volume to instance"
method: POST
path: "/instances/{id}/volumes/{volumeId}"
---

# Attach volume to instance

`POST /instances/{id}/volumes/{volumeId}`

## Path parameters

- `id` string, required
- `volumeId` string, required

## Request body

- AttachVolumeRequest
  - `mount_path` string, required — Path where volume should be mounted
  - `readonly` boolean — Mount as read-only

## Response `200`

Volume attached

- 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

- `404` — Instance or volume not found
- `409` — Conflict - volume already attached
- `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)