Port forwarding
Open TCP and UDP ports, and route a domain over HTTP or HTTPS to a server that shares its public address.
Some Helipod servers run on Helipod's own hosts and share a public IPv4 address with other servers. Each of them gets a port range on that address. To reach a program on the server from the internet, you forward a public port from the range to a port inside the server, or route a domain to it over HTTP (port 80) or HTTPS (port 443).
Only on servers with a shared address
Port forwarding exists only on these servers. On every other server the routes here answer 409 FEATURE_NOT_AVAILABLE: such a server has its own address, and you open ports with the firewall instead. Call GET /vps/:id/ports to find out which kind a server is.
Adding and removing a port changes the running server: the server must be running (409 INSTANCE_NOT_RUNNING otherwise) and not busy (409 VPS_BUSY). Nothing here costs money.
The port object
{
"id": "2b7c1e94-5d3a-4f8e-9a61-0c4d2e7f8b13",
"port": 20145,
"protocol": "tcp",
"internalPort": 5432,
"domain": null,
"description": "Postgres",
"active": true,
"createdAt": "2026-10-16T09:12:03.000Z"
}| Field | Type | Description |
|---|---|---|
port | number | The public port: in the server's port range, or 80 / 443 for a domain route. |
protocol | string | tcp, udp, both (TCP and UDP), http or https. |
internalPort | number | The port inside the server that receives the traffic. |
domain | string | null | The domain of an http or https route. |
active | boolean | true once the forward is in place on the host. |
List ports
/vps/:id/portscurl https://api.helipod.io/api/vps/1f757fd5-98d1-490a-81a0-58b5798a5815/ports \
-H "Authorization: Bearer hel_your_key"{
"success": true,
"data": {
"portRange": { "start": 20141, "end": 20159 },
"ports": [
{ "id": "2b7c1e94-5d3a-4f8e-9a61-0c4d2e7f8b13", "port": 20145, "protocol": "tcp", "internalPort": 5432, "domain": null, "description": "Postgres", "active": true, "createdAt": "2026-10-16T09:12:03.000Z" }
]
}
}portRange holds the public ports you can use for TCP and UDP forwards, both ends included.
Forward a port
/vps/:id/ports201 with the port object.Prop
Type
Reach Postgres inside the server on public port 20145:
curl -X POST https://api.helipod.io/api/vps/1f757fd5-98d1-490a-81a0-58b5798a5815/ports \
-H "Authorization: Bearer hel_your_key" \
-H "Content-Type: application/json" \
-d '{ "port": 20145, "protocol": "tcp", "internalPort": 5432, "description": "Postgres" }'Connect to the server's publicIp on port 20145.
HTTP and HTTPS routes
- The domain is routed by name, so many servers can share ports 80 and 443. A domain can route to one server only: a domain another server uses answers
409 PORT_TAKEN, and so does a second route of the same protocol for it on this server. - HTTPS is passed through to your server as it is: your server holds the certificate and terminates TLS. Requests for
/.well-known/acme-challenge/on the domain reach port 80 of your server, so a tool such as certbot can issue the certificate there. - An HTTPS route whose
internalPortdoes not answer TLS is not set up.
Errors
| Status | Code | When |
|---|---|---|
400 | INVALID_PORT | A port outside the range, http not on port 80, https not on 443, a missing or invalid domain, or a domain on a TCP/UDP forward. error says which. |
409 | PORT_TAKEN | The public port is already forwarded, or the domain already has a route. |
409 | INSTANCE_NOT_RUNNING | Start the server first. |
409 | FEATURE_NOT_AVAILABLE | The server has no shared address. |
Remove a forward
/vps/:id/ports/:allocationIdcurl -X DELETE https://api.helipod.io/api/vps/1f757fd5-98d1-490a-81a0-58b5798a5815/ports/2b7c1e94-5d3a-4f8e-9a61-0c4d2e7f8b13 \
-H "Authorization: Bearer hel_your_key"{ "success": true, "data": { "id": "2b7c1e94-5d3a-4f8e-9a61-0c4d2e7f8b13", "deleted": true } }An unknown id answers 404 PORT_NOT_FOUND.