Set the application port

PATCH /v1/infra/servers/:id/port

Sets the TCP port to which the tunnel agent proxies incoming HTTPS requests from the subdomain. By default the tunnel goes to :3000 — this is the platform standard, and most applications should listen on it. This endpoint is needed in rare cases: the application runs on a different port for historical reasons, or you want 0 (auto-detect) so the agent finds the listening port itself. Ports 1–1023 are forbidden — these are system ports (SSH, HTTP, HTTPS, SQL), and using them would create a risk of redirecting traffic to service processes.

Parameters

Request fields (body)

Examples

curl — personal key

# Set port 8080
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

# Automatic detection
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 0}'

curl — OAuth application

curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/port`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ port: 8080 }),
  }
)
const { data } = await res.json()
console.log(`Application port: ${data.port}`)

JavaScript — OAuth application

await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/port`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ port: 0 }),
  }
)

Response fields

Response example

{
  "success": true,
  "data": { "port": 8080, "mode": "manual", "verified": true, "pinned": true }
}

Error response example

409 — the agent rejected the port change:

{
  "success": false,
  "error": {
    "code": "PORT_NOT_APPLIED",
    "message": "The server agent runs in fixed-port mode and cannot change its port at runtime. Repair the server (POST /v1/infra/servers/:id/repair) to switch the agent to port auto-detection, then retry.",
    "agentError": "NO_SCANNER"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• System ports (1–1023) are forbidden for a reason. SSH (22), HTTP (80), HTTPS (443), DNS (53), PostgreSQL (5432), MySQL (3306) — opening a tunnel on them would create a risk of redirecting external traffic to service processes inside the virtual machine.
• How port: 0 works. The agent reads the machine's listening sockets from /proc/net/tcp and /proc/net/tcp6, probes each port with an HTTP request and points the tunnel at the one that answered. Among the ports that answered, it takes the lowest number, except 80 and 443 — those two are chosen only when nothing else answered. The restriction on system ports 1–1023 applies to setting the port explicitly with this call, and does not affect auto-detection. Five ports never take part in auto-detection: 22, 2375, 2376, 4243 and 9200. The machine's service interfaces answer on those ports, and publishing such an interface on the subdomain would open it to the internet. The filter applies to auto-detection only — the agent accepts any explicitly set port from the allowed range, so keep service interfaces out of the tunnel. Auto-detect suits applications that pick a port dynamically at startup.
• Auto-detect also considers processes that listen on 127.0.0.1 only. For a Black Hole application, that is the normal way to start: the agent reaches the application over the local interface, while the machine is closed from the outside. The consequence — a service process brought up on the machine only for local calls is indistinguishable from the application during auto-detection and can take the tunnel. When other processes that answer over HTTP run next to your application on the machine, set the application port explicitly with this call. Then the choice does not depend on who else is listening.
• Auto-detect holds on to the previous port while something still answers on it. The scanner does not switch to a new port on a single observation: while a responding process is alive on the previous port, the tunnel target stays on it — so a brief stall of the application does not drop the tunnel onto a stub page. The practical consequence: if the application moved to another port and a live process stayed on the old one, auto-detection will not switch by itself. The way out is to set the port explicitly with this call, or to stop the process on the previous port. If the previous port simply became free, the switch happens on its own within about a minute. The hold does not apply to 80 and 443: when the target sits on one of them, auto-detection switches as soon as an application port answers.
• A pinned port survives both a wake and a repair. The pin is stored on the machine itself — as the local_http line in the agent settings at /etc/vibe-agent/config.yml. The value auto means auto-detection, while a value such as 127.0.0.1:8080 means a fixed port. The platform writes that line. On a pinned server this call rewrites it. An unpinned server becomes pinned once the port is confirmed — by a successful deploy that passed its healthcheck, or by a confirmed port change through this call — if pinning is enabled for your Bitrix24 account. A pinned server answers portPinned: true in GET /v1/infra/servers/:id, and once it is pinned both waking the server and /repair bring the agent back to the same port. On an UNPINNED regular server, repair sets auto-detection and the port is chosen again. For agents, bots and galaxy hosts, repair writes the fixed port from the database.
• port: 0 is returned in the response as 3000. This is not an error: "on auto-detect we return 3000 if nothing suitable was found". Check the actual listening port via /exec with the command ss -tlnp.
• The platform confirms the port change (data.verified). On an UNPINNED server, after set_port the platform probes the agent and checks that the tunnel actually proxies to the requested port. verified: true — routing is ready. verified: false + data.warning — the agent accepted the command but the confirmation did not arrive. Retry the request in a few seconds. /repair is not the fix here and makes things worse: a port set by that command lives in the agent's memory, so the restart during a repair discards it and returns the agent to auto-detection. 409 PORT_NOT_APPLIED — the agent did not accept the change at all: with agentError: NO_SCANNER the server runs in fixed-port mode (run your application on the current port, or /repair to switch to auto-detection); with a different agentError the agent is outdated (/repair updates it).
• On a PINNED server this call works differently — but not right away. The port is applied by rewriting the agent settings and restarting the agent, and verified: true means the settings carry the requested port and the agent is back online. The tunnel drops for a few seconds while that happens. port: 0 removes the pin and returns the agent to auto-detection. If the agent did not make it back in time, the response carries verified: false — that is not a failure: the port is already written and takes effect once the agent comes up. Distinct failures: 502 AGENT_CONFIG_WRITE_FAILED — the machine refused to write the settings (run /repair), 502 GATEWAY_ERROR — the command never reached the machine (retry later), 409 PORT_NOT_APPLIED without agentError — nothing listens on the requested port.
• The behavior above starts after the agent's first restart, not the moment portPinned: true appears. The path is chosen by the state of the MACHINE, not by the response field: until the agent has restarted, it still runs the scanner, and the call behaves as on an unpinned server — the tunnel does not drop, and 409 PORT_NOT_APPLIED with an agentError can arrive. A restart happens on a server wake, a deploy or a repair. So a handler written against portPinned must be ready for both modes.

See also

• Full deploy
• Tunnel metrics
• Run a command