---
id: browser-console
title: Browser console
sidebar_label: 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](./ssh-keys.md). 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                  |