API Reference

Network

Configure network policies for your VM - internet access, inbound/outbound firewall rules, private links between VMs, and dedicated outbound IPs.

VM firewall

One host firewall policy manages private IPv4 ports and direct public IPv6 TCP ports. In the dashboard these appear as Private, Public TCP, or Both. Private ingress sources and gateway-access settings continue to apply. Public exposure changes require the VM owner; a delegated vm.network editor may change only private ports. Both paths apply the same account and namespace authorization.

GET /v1/vms/{vmId}/network/firewall
PUT /v1/vms/{vmId}/network/firewall

GET returns:

{ "version": 1, "revision": 7, "private_ports": [5432], "public_tcp_ports": [443] }

PUT requires both port lists and the revision from the latest read:

{ "expected_revision": 7, "private_ports": [5432], "public_tcp_ports": [443] }

An empty list denies that exposure. private_ports: [-2] permits all private ports; public ports never support a wildcard. Each explicit list has at most 50 integer ports (1–65535); public ports exclude 9990 and 9999. A shared revision covers firewall and IPv6 updates, including existing private ingress updates. Stale writes return 409 (firewall_revision_conflict) without applying the change. Inspect current state after 503 before retrying.

SDK: client.vm(vmId).network.getFirewall() and .setFirewall(settings), also available on client.vms.network with vmId as the first argument. Types: FirewallState and FirewallUpdateParams.

Private established connections may finish after a port removal. Public port removal or IPv6 disable blocks established traffic too. Enforcement uses the existing host firewall; no guest firewall is installed.

The API accepts both /v1/vms/... and /vms/... through the same handlers and authorization. The direct alias stays pinned to v1 when later versions are introduced; SDK defaults and OAuth URLs remain versioned.

Public IPv6

Use the IPv6 endpoints to inspect allocation and activate the public rules stored in the VM firewall. IPv6 is off by default. Only the VM owner can update it; account and namespace authorization still apply.

GET /v1/vms/{vmId}/network/ipv6
PUT /v1/vms/{vmId}/network/ipv6
curl "https://api.oblien.com/v1/vms/$VM_ID/network/ipv6" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Read the current revision before sending PUT. Omit tcp_ports to preserve the central firewall rules:

{ "enabled": true, "expected_revision": 7 }

Example response:

{
  "supported": true,
  "enabled": true,
  "address": "2001:db8:1::abcd",
  "tcp_ports": [5432],
  "revision": 1,
  "active": true,
  "outbound": "reply_only"
}
FieldMeaning
supportedWhether public IPv6 is configured on the VM's node
enabledSaved opt-in setting
addressProvider-assigned IPv6; absent before allocation
tcp_portsExplicit public TCP ports; an empty list opens nothing
revisionShared firewall revision; use it as the next expected_revision
activeCurrent firewall authorization, independent of whether an application is listening
reasonInactive reason, such as disabled, no_open_ports, vm_not_running, network_quota, billing_authorization or inactive
outboundreply_only: replies to permitted incoming TCP, with no guest-initiated IPv6 egress

enabled must be boolean. expected_revision must be a nonnegative safe integer below Number.MAX_SAFE_INTEGER. Supply at most 50 integer ports between 1 and 65535; 9990 and 9999 are reserved. To disable while preserving the rules, send enabled: false and the latest revision. Existing callers may still supply tcp_ports to explicitly replace the central public port list; [] clears it. Ports are closed for existing connections too.

A stale revision returns 409 (public_ipv6_revision_conflict). Read again and review the desired change; do not blindly retry an old enable. A node or guest failure can return 503. Inspect state before retrying because saved intent and active access can differ. GET remains usable when the VM is stopped or overdue, subject to ordinary access controls.

The SDK 3.2.0 methods are client.vms.network.getPublicIPv6(vmId) and setPublicIPv6(vmId, settings), also available on client.vm(vmId).network. See the connection and dashboard guide.

Get network

Get the current network configuration.

const network = await ws.network.get('ws_a1b2c3d4');
GET /v1/vms/:vmId/network
curl "https://api.oblien.com/v1/vms/ws_a1b2c3d4/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "ip": "10.0.0.15",
  "gateway": "10.0.0.1",
  "public_access": false,
  "allow_internet": true,
  "ingress": [],
  "ingress_ports": [],
  "egress": [],
  "egress_ports": [],
  "outbound_ip": null,
  "outbound_mode": "managed",
  "outbound_proxy": null,
  "private_links": []
}

Response fields

FieldTypeDescription
ipstringVM private IP address (use this for direct connections)
gatewaystringNetwork gateway
public_accessbooleanWhether public inbound traffic is allowed (required for gateway access)
allow_internetbooleanWhether outbound internet is allowed
ingressstring[]Allowed inbound source IPs (managed automatically via private links)
ingress_portsnumber[]Allowed inbound ports
egressstring[]Allowed outbound hosts/CIDRs
egress_portsnumber[]Allowed outbound ports
outbound_ipstring|nullAssigned primary outbound proxy IP; managed failover may use another exit address
outbound_mode"managed"|"custom""managed" uses the assigned pool proxy and provider failover policy; "custom" uses your own proxy without automatic host fallback. See Custom outbound proxy
outbound_proxyobject|nullPresent only when outbound_mode === "custom". Shape: { host, port, protocol, has_credentials } — the password itself is never returned
private_linksobject[]Linked VMs with resolved IPs (see Private Links)

The ip field is the VM's internal network address. You'll need this when making direct VM-to-VM calls. You can also get it from the raw token endpoint, which returns both the IP and the connection token in one call.


Update network

Partially update network policy. Only the fields you provide are changed.

await ws.network.update('ws_a1b2c3d4', {
  allow_internet: true,
  ingress_ports: [80, 443, 3000],
  egress: ['api.github.com', 'registry.npmjs.org'],
  public_access: false,
});
PATCH /v1/vms/:vmId/network
{
  "allow_internet": true,
  "ingress_ports": [80, 443, 3000],
  "egress": ["api.github.com", "registry.npmjs.org"],
  "public_access": false
}
curl -X PATCH "https://api.oblien.com/v1/vms/ws_a1b2c3d4/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_internet": true,
    "ingress_ports": [80, 443, 3000],
    "egress": ["api.github.com"]
  }'

Parameters

All fields are optional:

ParameterTypeDescription
allow_internetbooleanEnable/disable outbound internet. Setting to false clears egress
ingress_portsnumber[]Allowed inbound ports (1–65535, max 50 entries)
egressstring[]Allowed outbound hosts/CIDRs (max 50 entries, printable ASCII)
public_accessbooleanAllow public inbound traffic (required for gateway access)
private_link_idsstring[]VM IDs to link - resolved to private IPs and added to firewall ingress (see Private Links)
outbound_mode"managed"|"custom"Set to "custom" to route through your own proxy (requires custom_proxy), "managed" to revert to the pool IP. See Custom outbound proxy
custom_proxyobjectRequired when outbound_mode: "custom". See Custom outbound proxy for shape

Validation rules

  • Port numbers must be between 1 and 65535
  • Maximum 50 entries per list (ingress, egress, ingress_ports)
  • Hosts must be printable ASCII characters
  • Setting allow_internet: false forces egress: []
  • public_access: true adds the host keyword to the ingress list

Private links allow VM-to-VM communication over the internal network. By default, every VM is network-dark - no inbound traffic is allowed from any source, including other VMs in the same account. Private links explicitly whitelist specific VMs.

When you set private_link_ids on a VM, the platform resolves each VM ID to its internal IP and adds it to the target's firewall ingress. The linked VMs can then reach the target over the private 10.x.x.x network.

// Allow ws_caller to reach ws_target
await ws.network.update('ws_target', {
  private_link_ids: ['ws_caller'],
});
// Allow multiple vms
await ws.network.update('ws_target', {
  private_link_ids: ['ws_caller_1', 'ws_caller_2', 'ws_orchestrator'],
});
PATCH /v1/vms/:vmId/network
{
  "private_link_ids": ["ws_caller_1", "ws_caller_2"]
}
curl -X PATCH "https://api.oblien.com/v1/vms/ws_target/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "private_link_ids": ["ws_caller_1", "ws_caller_2"] }'

How it works

  1. You provide VM IDs (not raw IPs) in private_link_ids
  2. The platform resolves each ID to its internal 10.x.x.x IP
  3. Resolved IPs are added to the target VM's firewall ingress list
  4. The public_access state is preserved - private links don't affect gateway access
  5. Only VMs that successfully resolve to an IP are linked

Response

The update returns the resolved link IDs:

{
  "success": true,
  "private_link_ids": ["ws_caller_1", "ws_caller_2"]
}

Viewing linked VMs

The GET /network response includes resolved private link details:

{
  "private_links": [
    {
      "id": "ws_caller_1",
      "ip": "10.40.0.5",
      "name": "my-agent",
      "image_logo": "node",
      "image_color": "#3C873A"
    },
    {
      "id": "ws_caller_2",
      "ip": "10.40.0.12",
      "name": "orchestrator",
      "image_logo": "python",
      "image_color": "#306998"
    }
  ]
}

Set private_link_ids to an empty array to remove all links:

await ws.network.update('ws_target', {
  private_link_ids: [],
});

Private links are one-directional. Linking ws_caller → ws_target allows the caller to reach the target, but the target cannot reach the caller unless you also create a link in the other direction.

Private links are required for direct VM-to-VM access to the Runtime API. Without a link, the target's firewall blocks the connection even if the caller knows the IP and has a valid token.


List available outbound IPs

Get all Zones IPs in the pool that can be assigned to a VM as a dedicated outbound IP.

GET /v1/zone/mine
curl "https://api.oblien.com/v1/zone/mine" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "proxies": [
    { "ip": "203.0.113.50", "country_code": "US" },
    { "ip": "198.51.100.12", "country_code": "DE" }
  ]
}

Use any ip value from this list when calling Apply outbound IP below.


Apply outbound IP

Assign the VM's primary managed outbound proxy IP. Provider-managed failover can select a different source IP if that proxy fails. For a third-party firewall that requires a fixed exit address, use a customer-controlled proxy with the required availability policy.

POST /v1/vms/:vmId/network/ip
{
  "ip": "203.0.113.50"
}
curl -X POST "https://api.oblien.com/v1/vms/ws_a1b2c3d4/network/ip" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ip": "203.0.113.50" }'

Parameters

ParameterTypeRequiredDescription
ipstringYesOutbound IP from GET /zone/mine

Response

{
  "success": true,
  "ip": "203.0.113.50",
  "country_code": "US"
}

Errors

CodeStatusCause
ip_required400ip field missing from request body
invalid_zone_ip400IP is not in the available pool
zone_missing_host422Zone configuration is incomplete
pool_empty503Egress zone temporarily unavailable

Custom outbound proxy (BYOP)

Provider-managed failover does not override a customer-supplied proxy. See managed egress failover for transport scope, retry guarantees, and accounting.

Bring your own HTTP/HTTPS proxy and route this VM's outbound traffic through it. Use this when you need outbound traffic to exit from an IP you control — for SOC2 audits, IP allowlists managed by a third party, or carrier-grade proxy providers.

Custom outbound proxy is a Scale plan feature. VMs on Free, Hobby, or Pro plans will receive a plan_required (HTTP 402) error. Upgrade in the billing dashboard to enable it.

How it works

When you set a custom HTTP/HTTPS proxy, the platform installs host-side rules for outbound TCP ports 80 and 443. The VM doesn't need to be proxy-aware: no HTTPS_PROXY environment variable or SDK changes inside the VM are needed. Other TCP ports and UDP retain their existing network policy.

Before applying, the platform runs a live CONNECT oblien.com:443 preflight against your proxy. If the preflight fails (unreachable, auth rejected, wrong protocol), the request is rejected and your previous outbound configuration is preserved — bad proxies cannot break outbound traffic.

Set custom proxy

await ws.network.setCustomProxy('ws_a1b2c3d4', {
  host: '203.0.113.10',
  port: 3128,
  protocol: 'http',
  username: 'my-user',
  password: 'my-pass',
});

Or use the generic update if you want to combine BYOP with other network changes:

await ws.network.update('ws_a1b2c3d4', {
  outbound_mode: 'custom',
  custom_proxy: {
    host: '203.0.113.10',
    port: 3128,
    protocol: 'http',
  },
  ingress_ports: [443],
});
PATCH /v1/vms/:vmId/network
{
  "outbound_mode": "custom",
  "custom_proxy": {
    "host": "203.0.113.10",
    "port": 3128,
    "protocol": "http",
    "username": "my-user",
    "password": "my-pass"
  }
}
curl -X PATCH "https://api.oblien.com/v1/vms/ws_a1b2c3d4/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "outbound_mode": "custom",
    "custom_proxy": {
      "host": "203.0.113.10",
      "port": 3128,
      "protocol": "http",
      "username": "my-user",
      "password": "my-pass"
    }
  }'

Clear custom proxy (revert to managed)

await ws.network.clearCustomProxy('ws_a1b2c3d4');
PATCH /v1/vms/:vmId/network
{ "outbound_mode": "managed" }
curl -X PATCH "https://api.oblien.com/v1/vms/ws_a1b2c3d4/network" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "outbound_mode": "managed" }'

Parameters

ParameterTypeRequiredDescription
hoststringYesProxy IPv4 address. Hostnames are not accepted — pre-resolve to an IP. Reserved/private ranges (RFC1918, loopback, link-local, multicast, etc.) are rejected
portnumberYesProxy port, 1–65535
protocol"http"|"https"NoProxy protocol. Defaults to "http". Both speak HTTP CONNECT — "https" adds TLS to the VM↔proxy hop
usernamestringNoUsername for Proxy-Authorization. If set, password is required
passwordstringNoPassword for Proxy-Authorization. Required if username is set. Printable ASCII only, no : @ / ? or whitespace

Reading back the proxy

GET /vms/:vmId/network returns the proxy as outbound_proxy:

{
  "outbound_mode": "custom",
  "outbound_proxy": {
    "host": "203.0.113.10",
    "port": 3128,
    "protocol": "http",
    "has_credentials": true
  }
}

The password itself is never returned — only has_credentials: true|false so the dashboard can show a "saved" indicator without leaking the secret.

Errors

CodeStatusCause
plan_required402VM owner is not on the Scale (or Enterprise) plan
missing_custom_proxy400outbound_mode: "custom" was sent without a custom_proxy object
invalid_outbound_mode400outbound_mode was not "custom" or "managed"
invalid_proxy_host400host is not a valid IPv4
reserved_proxy_host400host is in a reserved/private range (e.g. 10.0.0.0/8, 192.168.0.0/16)
invalid_proxy_port400port is not an integer in 1–65535
invalid_proxy_protocol400protocol is not "http" or "https"
invalid_proxy_credentials400Credentials contain forbidden characters or username was set without password
preflight_protocol_mismatch400The proxy responded but does not speak the protocol you specified
preflight_auth_required401The proxy rejected your credentials
preflight_bad_status502The proxy returned a non-2xx status to CONNECT
preflight_unreachable502The proxy address is unreachable from the host
preflight_timeout504The proxy did not respond within the preflight window
preflight_closed502The proxy closed the connection without responding

Security notes

  • The host is validated against a list of 16 reserved IPv4 ranges before any kernel state is touched. You cannot point the proxy at the host's loopback or internal network.
  • Credentials are sent to your proxy as a base64-encoded Proxy-Authorization: Basic … header. The base64 alphabet (A-Za-z0-9+/=) means credentials cannot inject extra HTTP headers regardless of what characters you put in them — but we still reject :, @, /, ?, and whitespace in the validator for defense in depth.
  • nftables rules are built with typed netlink structs (host IP becomes 4 raw bytes, port becomes a uint16). There is no string-rendered rule path, so a malicious-looking IP cannot inject extra nftables statements.
  • When the VM is deleted, the per-VM nftables chain and cached credentials are torn down as part of normal VM cleanup.

Learn more about networking concepts in Concepts: Networking.

Rotate public IPv6

POST /v1/vms/{vmId}/network/ipv6/rotate (also /v2) is an owner-only operation. Send { "expected_revision": 4, "request_id": "cdf0142c-04fc-4d18-8001-03ddda1db2d2" }. The revision is shared with the VM firewall. The request cannot choose an address or change ports.

A 200 response contains { operation, state }. The immutable operation receipt has request_id, previous_address, address, revision, created_at and a status that advances from pending to completed. state is the current IPv6 response, including optional rotation: { supported, available, policy, remaining_vm, remaining_owner, next_allowed_at, reason?, operation? }. The policy contains enabled, cooldown_seconds, vm_limit_24h and owner_node_limit_24h.

Persist and retry the original ID and revision after an uncertain response. A replay returns the original receipt and current state. Limits are provider-owned and enforced in the allocation transaction: currently 3600 seconds, three per VM and 20 per account per node in rolling 24-hour windows. A 429 public_ipv6_rotation_limited requires a fresh state read for next_allowed_at; conflicting revision, payload/scope or pending rotation return 409. Other customers and delegated public-network editors cannot rotate the address.

Rotation permanently retires the previous address and breaks its TCP connections. The VM, private networking, saved public port list and traffic quotas remain in place. Pending recovery is durable across daemon restarts. See rotation and retries for the full lifecycle and SDK 3.3.0 usage.