AnkraDocs
Console

API reference · Compute

Port forwarding

1 operation of the Ankra Cloud API: A TCP stream to a server's SSH port through its zone's gateway, for a client with no route to the server's address (ADR 0017).

A TCP stream to the server's SSH port, through its zone's gateway (WebSocket)#

GET/v1/servers/{id}/port-forward
Operation
open_server_port_forward
Credentials
API token, Portal session
Requires
Permission operate
Note
Reveals a credential or a live view; read-only support sessions are refused.

A WebSocket (send Connection: Upgrade and Upgrade: websocket) whose binary messages carry one TCP connection to port (22, the only port forwarded) of the server's public IPv6 address. A gateway of the server's zone makes the connection from inside the zone and the stream travels over the control plane's node bus, so the caller needs no route to the server: an IPv4-only network reaches an IPv6-only server. The server's firewall sees the connection come from one of networking.port_forward_sources in the zone's capabilities (the gateway's own address, or the pool gateway address); admit SSH from them. SSH keeps its own end-to-end authentication; the stream carries only its ciphertext. The forward needs an API token (a browser session gets 403, and a handshake from another site's origin is refused). Every forward opened is recorded in the audit log as server.port_forward_opened. It ends when either side closes, after 10 minutes without a byte either way, or after 12 hours; each account holds at most 32 open forwards per API replica (429). 503 when the zone's gateway does not answer (offline, or its node agent does not forward ports yet), 502 when it answered but could not connect.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
portqueryinteger

Responses

  • 101The WebSocket; binary messages carry the TCP stream both ways.
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The port is not a TCP port number, or not one that is forwarded (only 22 is).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 502A service the control plane depends on (headscale) did not answer; detail says how.
  • 503No capacity or address is free, or a host did not answer; try again later.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/servers/<id>/port-forward' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"