> ## 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. # Open a VM port > Opens one TCP or UDP port on a running VM. protocol defaults to tcp. public_port defaults to guest_port and must be in 1024-21999 or 23000-29999; ports the host itself serves are refused. A public port belongs to one VM per host and protocol, so a TCP port and a UDP port can share a number. A VM opens at most 16 ports. While the reservation is public the port is reachable from the internet on the host's public IP, so open only what the VM should serve publicly. A 202 response is acceptance: the port is opening until the host applies it. Poll the VM's ports until its status is open, private, or failed. On a public reservation the port is reachable from the internet on the host's public IP. For the full flow, see [Open ports on a VM](https://docs.ornn.com/guides/vm-access.md#open-ports-on-a-vm). ## OpenAPI ````yaml openapi.yaml POST /v1/orchestrator/nodes/{node_id}/virtual-machines/{vm_id}/ports 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, order books, 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: Order books description: >- Hourly order books for whole nodes, one VM per node: read books, trades, and quotes, place and cancel bids, and follow and end 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/{node_id}/virtual-machines/{vm_id}/ports: post: tags: - Virtual machines summary: Open a VM port description: >- Opens one TCP or UDP port on a running VM. protocol defaults to tcp. public_port defaults to guest_port and must be in 1024-21999 or 23000-29999; ports the host itself serves are refused. A public port belongs to one VM per host and protocol, so a TCP port and a UDP port can share a number. A VM opens at most 16 ports. While the reservation is public the port is reachable from the internet on the host's public IP, so open only what the VM should serve publicly. A 202 response is acceptance: the port is opening until the host applies it. Poll the VM's ports until its status is open, private, or failed. operationId: accessOpenVirtualMachinePort parameters: - name: node_id in: path required: true description: The VM's node_id from the reservation's VM list. schema: type: string format: uuid example: 33333333-3333-4333-8333-333333333333 - name: vm_id in: path required: true description: The VM's id from the reservation's VM list. schema: type: string format: uuid example: 66666666-6666-4666-8666-666666666666 requestBody: required: true content: application/json: schema: type: object required: - guest_port properties: guest_port: type: integer minimum: 1 maximum: 65535 public_port: type: integer description: Defaults to guest_port. protocol: type: string enum: - tcp - udp default: tcp example: guest_port: 8443 responses: '202': description: Port accepted. The body is the new port, opening. content: application/json: schema: $ref: '#/components/schemas/AccessVirtualMachinePort' example: id: 99999999-9999-4999-8999-999999999999 virtual_machine_id: 66666666-6666-4666-8666-666666666666 node_id: 33333333-3333-4333-8333-333333333333 protocol: tcp public_port: 8443 guest_port: 8443 status: opening failure: null created_at: '2026-10-22T18:00:00Z' '400': description: >- The VM port is not 1-65535, the public port is outside the allowed ranges, or the protocol is not tcp or udp (port_protocol_not_allowed). content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: public_port_not_allowed message: >- Choose a public port from 1024 to 21999 or 23000 to 29999. Ports the host itself uses are not available. '401': $ref: '#/components/responses/Unauthorized' '404': description: >- The VM, its node, or its reservation is absent or not owned by your organization. content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: virtual_machine_not_found message: Ornn could not find that virtual machine. '409': description: >- Another VM on this host holds the public port for that protocol (public_port_in_use), this VM already opens that VM port and protocol, the VM has 16 ports, the VM is not running, the reservation is switching networks (virtual_machine_busy), or its host needs a management update (port_forwarding_unavailable). content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: code: public_port_in_use message: >- Another VM on this host already uses this public port. Choose a different public port. default: $ref: '#/components/responses/Error' components: schemas: AccessVirtualMachinePort: type: object required: - id - virtual_machine_id - node_id - protocol - public_port - guest_port - status - created_at properties: id: type: string format: uuid virtual_machine_id: type: string format: uuid node_id: type: string format: uuid protocol: type: string enum: - tcp - udp public_port: type: integer description: >- The port on the host's public IP. Held for this VM while the reservation is private, so it opens again when the reservation switches back to public. guest_port: type: integer description: The port inside the VM that public_port forwards to. status: type: string enum: - opening - open - private - failed description: >- opening until the host applies the change; open when published on the host's public IP; private while the reservation is private (reach the VM at its private_ip instead); failed with failure set. failure: oneOf: - type: 'null' - type: object required: - code - message properties: code: type: string description: port_in_use_on_host or port_forwarding_failed. message: type: string created_at: type: string format: date-time Error: type: object properties: code: type: string detail: oneOf: - type: string - type: object required: - code - message properties: code: type: string message: type: string 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' 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.