> ## Documentation Index > Fetch the complete documentation index at: https://docs.ornn.com/llms.txt > Use this file to discover all available pages before exploring further. # Launch VM or Bare Metal access > Starts SSH access on an owned VM or Bare Metal reservation. If the reservation already has machines (for example after activation), launch sends the selected SSH keys to them and returns 202 with the current nodes. Otherwise launch selects nodes for the reservation, starts provisioning, and returns 201. Either response is acceptance, not readiness: poll the reservation's VMs or the node until SSH is ready. Repeating launch after machines exist does not reprovision them; it sends the keys again. Without ssh_key_ids, launch uses the keys already selected for the reservation, or every active SSH key in your organization. There is no VM size option: each VM receives its reserved GPUs and a matching share of the host's vCPUs, memory, and local disk, with at most 2 TiB of RAM. Launch does not attach storage volumes. Use Kubernetes or Slurm cluster routes for those access modes. CLI equivalent: `ornn launch --mode vm --key ` (or `--mode bare-metal`). Add `--wait` to wait for SSH. Walkthroughs: [VM](/guides/vm-access#use-the-api) and [Bare Metal](/guides/bare-metal-access#use-the-api). ## OpenAPI ````yaml openapi.yaml POST /v1/orchestrator/nodes/reservations/{reservation_id}/launch openapi: 3.1.0 info: title: Ornn compute API version: 1.0.0 description: >- Customer HTTP API for Ornn GPU capacity. It covers reserved capacity and nodes, VM and Bare Metal access, Kubernetes and Slurm clusters, SSH keys, storage volumes and GitHub repositories, private networks, monitoring, buying and selling capacity (Reserve, Market, Spot, and Relist), and billing. API keys are scoped to one organization and act with their creator's access there; account, team, and API-key management stay in the console. Most operations require an approved organization. See https://docs.ornn.com/api-keys to create a key and https://docs.ornn.com/guides/kubernetes-api for an end-to-end Kubernetes integration. Examples use fictional IDs and credentials. The info.version field identifies the contract revision, not a shared API path version. contact: email: support@ornn.com servers: - url: https://api.ornn.com description: Production security: - OrnnApiKey: [] tags: - name: Authentication - name: Reservations - name: GPU nodes - name: Clusters - name: Workers - name: Virtual machines description: >- Choose a VM disk, launch VM access on a reservation, and read each VM's status, launch progress, and SSH connection details. - name: Bare Metal description: >- Launch Bare Metal access on a reservation, read a host's readiness and SSH connection details, and reboot or hard reset it. - name: SSH keys description: >- Register public keys for your organization, choose which keys a VM or Bare Metal reservation uses, and queue key delivery to machines. Slurm clusters take organization key IDs at launch. Kubernetes API access does not use SSH keys. - name: Reserve description: >- Browse reserved-capacity listings and their terms, and post, cancel, or accept offers. Reserve listings are visible to approved organizations. - name: Market description: >- Browse relisted capacity and buy windows at the asking price, paid up front. Open to every member of your organization. - name: Spot description: >- Hourly order books for VMs with 1, 2, 4, or 8 GPUs on one node: read books, trades, and quotes, place and cancel bids, and follow fills. - name: Relist description: >- Sell whole nodes from a reservation you hold at your asking price, and manage those listings. - name: Storage description: >- Managed volumes, their files, and GitHub repository pulls. Volumes belong to the API key's creator in the key's organization. - name: Networks description: >- Organization private networks and the WireGuard configs you use to reach private machines and clusters. - name: Monitoring description: >- Machine telemetry and console logs for capacity your organization holds. Reads are limited to your reservation window. - name: Billing description: >- Invoices, billing summary, usage cost, Ornn credits, and account statements. Saving a card and paying invoices stay in the console. externalDocs: description: REST integration walkthrough url: >- https://docs.ornn.com/guides/kubernetes-access#provision-and-manage-through-rest paths: /v1/orchestrator/nodes/reservations/{reservation_id}/launch: post: tags: - Virtual machines - Bare Metal summary: Launch VM or Bare Metal access description: >- Starts SSH access on an owned VM or Bare Metal reservation. If the reservation already has machines (for example after activation), launch sends the selected SSH keys to them and returns 202 with the current nodes. Otherwise launch selects nodes for the reservation, starts provisioning, and returns 201. Either response is acceptance, not readiness: poll the reservation's VMs or the node until SSH is ready. Repeating launch after machines exist does not reprovision them; it sends the keys again. Without ssh_key_ids, launch uses the keys already selected for the reservation, or every active SSH key in your organization. There is no VM size option: each VM receives its reserved GPUs and a matching share of the host's vCPUs, memory, and local disk, with at most 2 TiB of RAM. Launch does not attach storage volumes. Use Kubernetes or Slurm cluster routes for those access modes. operationId: accessLaunchReservation parameters: - name: reservation_id in: path required: true description: An owned reservation ID (reservationId in reservation responses). schema: type: string format: uuid example: 11111111-1111-4111-8111-111111111111 requestBody: required: true description: Send an empty object to use the reservation's defaults. content: application/json: schema: $ref: '#/components/schemas/AccessLaunchRequest' examples: virtualMachine: summary: VM with one saved SSH key value: access_mode: virtual-machine network_mode: public ssh_key_ids: - 88888888-8888-4888-8888-888888888888 request_id: launch-2026-10-15-a bareMetal: summary: Bare Metal on a private network value: access_mode: bare-metal network_mode: private network_id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa ssh_key_ids: - 88888888-8888-4888-8888-888888888888 responses: '201': description: Provisioning started on the returned nodes. content: application/json: schema: $ref: '#/components/schemas/AccessNodeList' example: nodes: - node_id: 33333333-3333-4333-8333-333333333333 reservation_id: 11111111-1111-4111-8111-111111111111 controller_id: null status: bare-metal hostname: gpu-host-01 ip: 203.0.113.10 port: 22 username: tenant ssh_endpoint: tenant@203.0.113.10 gpu_type: H100 gpu_count: 8 authorized_key_fingerprints: [] authorized_key_metadata: [] keys_pushed_at: null reboot: null health_readiness: ready: true status: ready reasons: [] advisory_reasons: [] '202': description: >- The reservation already has machines. SSH keys were queued for delivery; the body lists the current nodes. content: application/json: schema: $ref: '#/components/schemas/AccessNodeList' example: nodes: - node_id: 33333333-3333-4333-8333-333333333333 reservation_id: 11111111-1111-4111-8111-111111111111 controller_id: null status: bare-metal hostname: gpu-host-01 ip: 203.0.113.10 port: 22 username: tenant ssh_endpoint: tenant@203.0.113.10 gpu_type: H100 gpu_count: 8 authorized_key_fingerprints: - SHA256:exampleFingerprint0000000000000000000000000 authorized_key_metadata: - fingerprint: SHA256:exampleFingerprint0000000000000000000000000 label: null status: installed linux_username: tenant pushed_at: '2026-10-15T00:06:40Z' failed_at: null failure_reason: null request_id: null keys_pushed_at: '2026-10-15T00:06:40Z' reboot: null health_readiness: ready: true status: ready reasons: [] advisory_reasons: [] '400': description: >- Invalid launch input, such as a VM with no disk available, an unsupported access mode, network_id without private networking, or a repeated SSH key ID. Some of these errors return detail as a plain code string. content: application/json: schema: $ref: '#/components/schemas/Error' examples: diskRequired: summary: No disk chosen for a VM value: detail: disk_required networkIdNotAllowed: summary: network_id sent with public networking value: detail: code: network_id_not_allowed message: >- A named network can only be used with Private VPN. Switch to Private VPN, or leave the network as Shared. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: The reservation is absent or not owned by your organization. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: reservation_not_found message: Ornn could not find that reservation. '409': description: >- The reservation cannot launch in its current state, no active SSH key is available, not enough nodes are free, or a node still has a previous environment to clean up. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: ssh_key_required message: >- Add an SSH key to your account before you launch. Machines are reached over SSH. '422': description: >- A disk was sent for Bare Metal. This error returns detail as a plain string. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: bare_metal_disk_not_allowed default: $ref: '#/components/responses/Error' components: schemas: AccessLaunchRequest: type: object properties: access_mode: type: string enum: - virtual-machine - bare-metal description: >- Defaults to the reservation's access mode. Use the mode your reservation was booked with. disk_id: type: - string - 'null' format: uuid description: >- VM only. Overrides the reservation's saved disk for VMs this request creates. When omitted, the saved disk is used; a VM launch with no disk available fails with disk_required. Must be omitted for Bare Metal. network_mode: type: string enum: - public - private default: public description: >- public exposes SSH on the host's public address. private connects the machine to your organization's private network. network_id: type: - string - 'null' format: uuid description: >- Private networking only. An existing private network in your organization. Omit it to use the organization's shared network. This does not create a network. node_count: type: - integer - 'null' minimum: 1 description: >- How many of the reservation's nodes to provision when launch starts provisioning. Defaults to every reserved node and cannot exceed it. Ignored when the reservation already has machines. ssh_key_ids: type: array uniqueItems: true items: type: string format: uuid description: >- Active SSH keys in your organization to authorize. The keys are also attached to the reservation. Omit to use the reservation's current keys, or every active organization key when none are selected. request_id: type: - string - 'null' description: >- Optional client token for this request. Reuse it when you retry the same launch so Ornn can recognize repeated commands. AccessNodeList: type: object required: - nodes properties: nodes: type: array items: $ref: '#/components/schemas/AccessNode' Error: type: object properties: code: type: string detail: oneOf: - type: string - type: object required: - code - message properties: code: type: string message: type: string AccessNode: description: >- A reserved host node. Fields not listed under Node are SSH key delivery and reboot state. allOf: - $ref: '#/components/schemas/Node' - type: object properties: authorized_key_fingerprints: type: array items: type: string description: >- Fingerprints of SSH keys installed for the tenant login on this host. authorized_key_metadata: type: array items: $ref: '#/components/schemas/AccessSshKeyDelivery' keys_pushed_at: type: - string - 'null' format: date-time description: When keys were last installed on this host. reboot: description: The latest tracked host reboot, or null. oneOf: - type: 'null' - $ref: '#/components/schemas/AccessRebootStatus' Node: type: object required: - node_id - reservation_id - controller_id - status properties: node_id: type: string format: uuid reservation_id: type: - string - 'null' format: uuid controller_id: type: - string - 'null' format: uuid description: The cluster currently holding this node, or null. status: type: string description: >- Node lifecycle or access mode, such as bare-metal; not a liveness signal. health_readiness: $ref: '#/components/schemas/NodeHealthReadiness' gpu_type: type: - string - 'null' gpu_count: type: - integer - 'null' hostname: type: - string - 'null' facility_id: type: - string - 'null' format: uuid cpu_type: type: - string - 'null' memory_bytes: type: - integer - 'null' format: int64 storage_bytes: type: - integer - 'null' format: int64 ip: type: string port: type: - integer - 'null' username: type: string ssh_endpoint: type: string enrolled_at: type: string format: date-time cleanup_state: type: string AccessSshKeyDelivery: type: object description: Delivery state of one SSH key on a host. properties: fingerprint: type: string description: SHA256 fingerprint of the public key. label: type: - string - 'null' status: type: string description: installed or failed. linux_username: type: string pushed_at: type: - string - 'null' format: date-time failed_at: type: - string - 'null' format: date-time failure_reason: type: - string - 'null' request_id: type: - string - 'null' AccessRebootStatus: type: object description: Progress of a host reboot. Hard resets are not tracked here. required: - packet_id - status - started_at properties: packet_id: type: string format: uuid description: Identifier of the reboot request. status: type: string enum: - in_progress - succeeded - failed started_at: type: string format: date-time detail: description: Why the reboot failed, when status is failed. oneOf: - type: 'null' - type: object properties: code: type: string message: type: string NodeHealthReadiness: type: object description: >- Heartbeat-based launch preflight returned on reservation nodes. A stale heartbeat blocks launch. Missing heartbeat evidence returns ready true with heartbeat:unknown in advisory_reasons; this is not proof of host reachability, GPU health, or workload readiness. Treat an absent readiness object as unknown, not as ready. The reservation-node serializer returns an object, never null. required: - ready - status - reasons - advisory_reasons properties: ready: type: boolean description: Whether the heartbeat preflight reports no blocking reason. status: type: string enum: - ready - blocked reasons: type: array items: type: string description: Blocking reasons, such as heartbeat:stale. advisory_reasons: type: array items: type: string description: Nonblocking advisories, such as heartbeat:unknown. example: ready: false status: blocked reasons: - heartbeat:stale advisory_reasons: [] responses: Unauthorized: description: >- The credential is missing, invalid, revoked, or no longer belongs to a current organization member. Check the HTTP status before parsing the body. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The credential lacks access to this operation, or the organization requires approval. An API key does not bypass these checks. content: application/json: schema: $ref: '#/components/schemas/Error' Error: description: >- Unsuccessful request. Check HTTP status first. Errors may have detail.code/detail.message, a string detail and optional top-level code, or an empty/non-JSON body. 401: invalid credential; 403: access or approval required; 404: not visible or credentials not ready; 409: lifecycle conflict; 429: back off; 5xx: service failure. Inspect current state before retrying mutations. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: OrnnApiKey: type: http scheme: bearer bearerFormat: ornn_sk_... description: >- Create an organization API key in Account Settings > Developer. Do not send this key to the Kubernetes API server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.