Skip to main content
Three endpoints, for three different situations, and each requires its own IAM action — reading a boot log, taking a picture of the screen, and holding a keyboard inside the guest are deliberately not the same grant.
Connect on the instance header offers three routes: SSH — From your terminal, which assembles the command for you — Serial — Text console in the browser — and Screenshot — Graphical console.
The boot transcript has no console control. Nothing in the web console reads console output; Serial attaches a live session, and that needs the instance running. For a guest that failed on the way up — the case the transcript exists for — reading it is API only.
GET /v1/instances/{instance_id}/console/output returns what the guest wrote to its serial console during its current boot: a bad fstab, a wrong kernel, a cloud-init failure. Nothing has to be installed in the guest, and it works on a stopped instance — which is exactly when you need it.max_bytes is a ceiling you may lower, not raise: the maximum is 65536 and larger values are clamped to it. When the transcript is longer than what you asked for, its beginning is dropped and truncated is true. The end is always kept.The transcript resets at every start, so a crashed guest’s last transcript is gone once it restarts — read it before you reboot. An instance that has never booted returns empty output, not an error.Requires compute:GetConsoleOutput.
GET /v1/instances/{instance_id}/console/screenshot returns a still image, normally image/png.This is the counterpart for everything a serial transcript cannot reach: a guest sitting in its boot manager, at a GRUB prompt, panicking before serial init, or booted from an image whose kernel was never told to log to the serial port. In those the transcript is empty and the screen holds the whole answer.A still, not a session — there is no remote desktop. The instance must be running; a stopped one has no display to capture and answers 409 rather than a blank frame.Requires compute:GetConsoleScreenshot.
GET /v1/instances/{instance_id}/console/serial upgrades to a WebSocket carrying an interactive session on the instance’s serial port. This is the way in when the network is broken: a wrong kernel, a full disk, a security group that locked you out.Raw bytes in binary frames, both directions. It is a terminal, not a protocol — point a terminal emulator at it. Authentication rides on the upgrade request, signed like any other call, so there is no separate token step. A non-WebSocket request answers 426.backlog_bytes replays already-written output before live output begins, so attaching to a quiet guest shows why it is quiet instead of an empty screen. Default 32768, maximum 65536, 0 disables it. The replay is the tail of the same recording /console/output serves, and the live session is the guest’s serial port, so the join is marked with a \r\n--- live ---\r\n line: history above it, the live console below. A guest printing at the instant you connect may lose a few bytes at that line; a quiet guest — the case replay exists for — is replayed exactly.One session per instance: opening a second disconnects the first, rather than interleaving two people’s keystrokes. A session ends after 15 minutes idle, or 4 hours regardless, and the close frame says which.Requires compute:StartSerialConsole, and the instance to be running.
This drops you at the guest’s own login prompt. It is not a backdoor — the guest’s credentials are still required, and nothing here grants access past what the guest itself allows.