Borealis Docs

Private networks and service discovery

Connect logical VMs on organisation-owned private networks and give services stable names.

Membership and access

A private network, or VNet, belongs to an organisation and a routing domain. Every active member can communicate with the other members. A VM can attach to several VNets in the same routing domain, but membership does not create peering between them. A process with access to both networks can still relay application traffic, so choose attachments with that trust boundary in mind.

Use private networks for VM-to-VM traffic. Ports and previews provide a separate way to expose an application endpoint. Creating a private service registration does not publish it to the internet.

Create and attach

Use the public API, a client with the current Runtime v2 operation catalogue, or hosted MCP. Inspect the operations available to your installation before changing resources.

  1. Select the intended organisation and create a VNet with a name and eligible routing domain.
  2. Attach the VMs that should communicate. Initial allocation can include vnetAttachments, or you can add an attachment to an existing VM.
  3. Retain the returned attachment and operation IDs. Poll pending network operations and inspect each attachment’s current connectivity.
  4. Start the application service and verify a request from another active member of the VNet.

Network inspection requires borealis.networks.read. Administration requires borealis.networks.write; changing membership or the VM’s DNS default requires borealis.networks.use and sandbox write access. Organisation and resource permissions still apply.

OperationAPI route
List or create networks/api/v1/vnets
Read a network/api/v1/vnets/{id}
List or create a VM attachment/api/v1/sandboxes/{vmId}/runtime/vnet-attachments
Read an attachment/api/v1/vnet-attachments/{id}
Inspect a mutation/api/v1/private-network-operations/{requestId}

Mutations use stable UUID idempotency keys. Updates and removals require the observed resource generation; reload after a conflict rather than overwriting a newer state.

Understand attachment status

Membership and connectivity are separate. An attachment can be attached but have inactive connectivity because its VM is suspended or has not been materialised. Attaching it does not wake the VM.

A running VM’s attachment can return HTTP 202 while connectivity is being established. Poll the operation, then inspect current connectivity. An old successful operation is not evidence that a service is reachable now. Check VM availability and application readiness as well.

Register a service name

Register a service through /api/v1/network-services, selecting its VNet, DNS label and target attachment. The target must belong to the same VNet. Use the returned qualified hostname, whose format is <label>.<vnet-id-without-hyphens>.borealis.internal.

Qualified names can resolve from authorised members of that VNet. Short names require an explicit default DNS attachment, configured through /api/v1/sandboxes/{vmId}/runtime/network-configuration. Adding an attachment does not choose that default automatically.

Service names can remain resolvable while their target is suspended or stopped. A DNS answer identifies the service; it does not prove that the application is running. Configure the application’s listening address, port and authentication, then test the connection.

Detach and remove

Detaching removes that attachment’s service registrations and interrupts its private connectivity. Detaching the DNS default clears it; another network does not become the default automatically.

VM deletion retires its memberships but does not delete its VNets. Network deletion is refused while attachments still reference it, including suspended or pending attachments. Inspect consumers and complete the intended detach operations before deleting a network.

See Sandbox lifecycle, Authentication and API reliability.