DigitalOcean API (unofficial showcase)
GET/v2/agents/sessions/{session_id}/port-forward/{port}

PortForwardSession opens a WebSocket tunnel to a guest TCP port.

Upgrades the request to a WebSocket and bridges it to one TCP connection on the session sandbox's guest port. Binary frames carry the opaque byte stream in both directions; the server closes with a descriptive WebSocket close code when the tunnel ends. This is the raw TCP tunnel; browser clients reaching the in-guest OpenHands Agent Server use the ingress URL (GET /v2/agents/sessions/{session_id}/ingress), which has replaced this bridge for them.

WebSocket is not expressible in OpenAPI; this documents the GET that initiates the upgrade handshake (HTTP 101 Switching Protocols). The handler dials the guest before upgrading, so a PAUSED session is woken and served rather than rejected. port must be between 1024 and 65535. A request without the WebSocket upgrade headers is answered 400 by the handshake layer.

2 parameters
session_idstringrequired
The session UUID.
portintegerrequired
The guest TCP port to connect to. Must be between 1024 and 65535.

12 status codes
101Switching Protocols. The WebSocket handshake succeeded and the connection is now a binary tunnel to the guest port.
400The request is not a valid WebSocket upgrade (missing Upgrade/Connection headers). Returned by the handshake layer as plain text.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
402The team is blocked by the prepayment gate.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403The port is outside 1024-65535, or the session belongs to another team.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404The resource was not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409The session has no sandbox.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
423This session is unavailable; contact support.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
502Could not reach the guest port (nothing listening, or the guest dial failed).
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: The request is not a valid WebSocket upgrade (missing Upgrade/Connection headers). Returned by the handshake layer as plain text. A 401 is returned: Authentication failed due to invalid credentials. A 402 is returned: The team is blocked by the prepayment gate. A 403 is returned: The port is outside 1024-65535, or the session belongs to another team. A 404 is returned: The resource was not found. A 409 is returned: The session has no sandbox. A 423 is returned: This session is unavailable; contact support. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. A 502 is returned: Could not reach the guest port (nothing listening, or the guest dial failed). Any other status is an error: There was an unexpected error.