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>.
- The ticket opens a connection for 60 seconds (
expires_at) and once: the first WebSocket burns it, a second one with the same ticket is refused. Ask for a ticket when the user clicks "Console", not in advance. - Every call issues a new ticket;
Idempotency-Keyis not used here. Calls count against the write budget (20 a minute). - A session ends after 1 hour without keyboard, mouse or clipboard input, and after 4 hours in any case. At most 10 sessions of one project are open at a time. To reconnect, ask for a new ticket.
- The server must be running (
409 server_not_runningotherwise); a router has no console (409 router_console_forbidden). A project suspended for non-payment gets402 service_suspended; an overdue invoice alone does not close the console. - When the server or its project moves to another owner, unused tickets of the previous owner stop working and open sessions are closed.
- The console has no power menu: use the power actions (
POST /v1/servers/{id}/actions/power-onand the others).
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:
- Subprotocol (preferred). Connect to
wss://novnc.fiberax.com:12000/fx/v1/wswithout a query string and offer two subprotocols:binaryandfxt.<ticket>. The ticket then stays out of every URL and log. The server picksbinary; withfxt.<ticket>alone it picks none, and most WebSocket clients then close the connection. - Query string. Connect to
websocket_urlas it is: the ticket is itstparameter. Use this when your client cannot set subprotocols.
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:
- Your customer clicks "Console". Your backend checks that this customer may open this server, calls
POST /v1/servers/{id}/consolewith your key (an account key with console access and theFiberax-Projectheader, or the project key of that customer), and keeps the ticket on the server side. - 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. - Your proxy opens
websocket_urlupstream (or the bare/fx/v1/wswith the subprotocolfxt.<ticket>) and relays frames until either side closes. Binary frames only; do not buffer, do not transform.
Rules for the proxy:
- Open the upstream within 60 seconds of the call, and only once per ticket.
- Offer upstream only your own subprotocols:
binary, plusfxt.<ticket>if you send the ticket that way. Do not forward theSec-WebSocket-Protocolheader of your customer's browser: afxt.value from the browser would replace your ticket. - Allow long idle reads: a quiet console sends little. Set the read timeout of the proxy above one hour, so the session ends by the platform's own limits and not by your proxy.
- Keep the ticket out of your logs, like a password: it opens the screen of that server for 60 seconds. When it travels in the upstream URL, both the access log and the error log of the proxy can write it.
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.