vantage-docs/docs/vantage/browser-console.md

id, title, sidebar_label

id	title	sidebar_label
browser-console	Browser console	Browser console

An SSH, RDP or VNC session in a browser tab, with no client software and no inbound port on the target beyond the one the protocol already uses.

Protocol handling is Apache Guacamole's the control plane proxies a WebSocket to a guacd daemon and manages credentials around it.

Requirements

• guacd running and reachable from the server. The bundled Compose stack includes it; GUACD_ADDR defaults to guacd:4822.
• KEY_ENCRYPTION_KEY set, since every credential involved is stored encrypted.
• Network reachability from the control plane to the target on the protocol port. This is the one part of Vantage that is not agent-mediated: guacd connects directly, so a machine reachable only by its agent cannot be consoled.

Opening a session

From a server's page, choose Console. Then:

1. The UI calls POST /api/console/connect, which mints a one-time session token.
2. The browser opens a WebSocket to GET /api/console/tunnel with that token.
3. The server marks the token consumed atomically, so a second use cannot race and proxies the connection to guacd.

Credentials

SSH

Authenticates with a private key stored in the key library. The key must have its private half uploaded; a public-only key cannot open a session.

RDP and VNC

You supply credentials when connecting. They are encrypted, single-use, and consumed when the tunnel opens. They are not retained for the next session.

:::info Why single-use A stored console credential is a standing grant to that machine for anyone who can reach the endpoint. Consuming it at tunnel-open means a leaked session token is worth one connection at most, and only until it is used. :::

Session behaviour

Closing the tab ends the session. There is no reconnect and no session persistence reopening mints a new token and a new connection.

Auditing

Opening a console is an audited action, with actor, server and time. What happens inside the session is not recorded: there is no session capture or keystroke log. If you need that, it has to come from the target machine.

When it does not work

Symptom	Cause
Connects then closes immediately	guacd unreachable check GUACD_ADDR and that the container is up
SSH refuses the key	The stored key has no private half, or is not in the target's authorized_keys
RDP fails on a fresh credential	Credentials are consumed on open; a retry needs them entered again
Hangs at connecting	The control plane cannot reach the target on the protocol port