Server console

The console is the screen, keyboard and mouse of a running server, the same one the client area opens with its Console button. It does not need the network inside the guest, so it is the way back into a server whose firewall, SSH or network settings lock you out, and the way to watch a server boot.

One call issues a one-time ticket; the ticket opens one console session. There is no VNC password to handle: the platform authenticates to the server itself and hands you the screen. Getting started covers keys, calls and errors.

1. A key with console access

Console access is a separate permission of a key. On the API tokens page, issue a key with Read and write access and tick Server console. Both a project key and an account key can carry it; keys issued without it, including every key you already have, get 403 insufficient_scope on the console. A team member also needs the VNC Console permission on the project.

2. Ask for a ticket

curl -X POST -H "Authorization: Bearer $FBX_KEY" \
     https://api.fiberax.com/v1/servers/12345/console
{
  "data": {
    "type": "vnc",
    "ticket": "eyJ2IjoxLCJraWQiOiJrMSJ9.c2lnbmF0dXJl",
    "expires_at": "2026-11-02T14:03:11+01:00",
    "websocket_url": "wss://novnc.fiberax.com:12000/fx/v1/ws?t=eyJ2IjoxLCJraWQiOiJrMSJ9.c2lnbmF0dXJl",
    "viewer_url": "https://novnc.fiberax.com:12000/fx/v1/viewer/#t=eyJ2IjoxLCJraWQiOiJrMSJ9.c2lnbmF0dXJl"
  }
}

With an account key, name the project as with any other server call: the header Fiberax-Project: <project id>.

3. The ready console page

The simplest use: open viewer_url in a new browser tab, or put it in an iframe of your own page. The ticket is in the URL fragment (#t=...): browsers do not send the fragment to any server, so it never reaches a log or a Referer header. The page shows the console scaled to the window and says so when the session ends.

<iframe src="https://novnc.fiberax.com:12000/fx/v1/viewer/#t=..." style="width:100%;height:600px;border:0"></iframe>

4. Your own client

websocket_url is a WebSocket that carries plain RFB 3.8 (the VNC protocol) with the security type None. Any RFB client that speaks WebSocket works, for example noVNC. Give the ticket in one of two ways:

If both are present, the subprotocol wins: a broken fxt. value is refused even with a good t. With noVNC:

import RFB from './core/rfb.js';
const r = await fetch('/my-backend/console?server=12345', { method: 'POST' }); // your backend asks the API
const t = (await r.json()).ticket;
const rfb = new RFB(document.getElementById('screen'), 'wss://novnc.fiberax.com:12000/fx/v1/ws',
                    { wsProtocols: ['binary', 'fxt.' + t] });
rfb.scaleViewport = true;

Ask for the ticket from your backend, never from the browser: the API key must not reach your users.

A refused connection gets an HTTP status instead of the WebSocket upgrade: 401 for a ticket that is malformed, expired or already used, 429 when the project already has 10 open sessions, 502 when the platform cannot reach the server's host. A refused ticket is spent: ask for a new one (for 429, after closing a session).

5. A portal of your own: proxy the WebSocket

If your customers use your portal and should see only your domain, your portal opens the console WebSocket on their behalf and relays bytes both ways. The flow:

  1. Your customer clicks "Console". Your backend checks that this customer may open this server, calls POST /v1/servers/{id}/console with your key (an account key with console access and the Fiberax-Project header, or the project key of that customer), and keeps the ticket on the server side.
  2. Your page opens a WebSocket to your own portal, for example wss://portal.example.com/console/<session>, where <session> is a short-lived id of your own, bound to that customer and that ticket.
  3. Your proxy opens websocket_url upstream (or the bare /fx/v1/ws with the subprotocol fxt.<ticket>) and relays frames until either side closes. Binary frames only; do not buffer, do not transform.

Rules for the proxy:

nginx in front of a backend that asks for the ticket and passes it to nginx in a header of its own (X-Console-Url here, set with auth_request):

location /console/ {
    auth_request /console-auth;                      # your backend: checks the customer, asks the API
    auth_request_set $console_url $upstream_http_x_console_url;
    resolver 1.1.1.1;                                # proxy_pass with a variable resolves at run time
    proxy_pass $console_url;                         # websocket_url, wss:// written as https:// for nginx
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Sec-WebSocket-Protocol "binary"; # never the browser's own value
    proxy_set_header Host novnc.fiberax.com:12000;
    proxy_ssl_server_name on;
    proxy_buffering off;
    proxy_read_timeout 3700s;
    access_log off;                                  # the upstream URL carries the ticket
    error_log /var/log/nginx/console-error.log crit; # and so does every error line about the upstream
}

Node.js with the ws package, the same idea in code:

import { WebSocketServer, WebSocket } from 'ws';
const wss = new WebSocketServer({ port: 8443, handleProtocols: () => 'binary' }); // plain ws: serve it as wss:// behind your TLS terminator
wss.on('connection', async (client, req) => {
  const ticket = await ticketFor(req);              // your check + POST /v1/servers/{id}/console
  if (!ticket) return client.close(1008);
  if (client.readyState !== 1) return;              // the customer left while you asked for the ticket
  const up = new WebSocket('wss://novnc.fiberax.com:12000/fx/v1/ws', ['binary', 'fxt.' + ticket]);
  up.binaryType = 'nodebuffer';
  const pending = [];
  client.on('message', (d) => up.readyState === 1 ? up.send(d) : pending.push(d));
  up.on('open', () => pending.splice(0).forEach((d) => up.send(d)));
  up.on('message', (d) => client.send(d));
  up.on('close', () => client.close());
  up.on('error', () => client.close(1011));        // ticket refused (401), limit (429), upstream down (502)
  client.on('close', () => up.close());
  client.on('error', () => up.close());
});

Your customer's browser then runs noVNC against your portal, with wsProtocols: ['binary'] and no ticket at all. Keep binary in that list: the nginx example always answers with this subprotocol, and a WebSocket client that offered none drops such an answer.