# Use an instance's console

> Open a browser console on an instance's screen, even when its network is down, and read its hardware and recent tasks.

Source: https://www.coritan.com/docs/cloud-compute/console/

In the dashboard:

- /dashboard/compute/…/console: https://www.coritan.com/dashboard/compute

The **Console** tab shows the instance's screen in your browser and sends it your keyboard and mouse, as a monitor and keyboard plugged into the machine would. It works while the instance has no network. Use it when SSH does not answer, for example after a firewall change locks you out, or to watch the instance boot.

Below the screen, the tab shows what the instance is using, what its guest agent reports, its virtual hardware and the tasks its host ran for it.

## Before you begin

- The instance is running. Start it from the header if it is stopped, as [Start, stop and restart an instance](/docs/cloud-compute/power/) describes.
- The instance is not suspended. The console does not connect to a suspended instance.
- To sign in at the screen, you need the password of the instance's user account. We do not show the password the instance was created with, so [reset the password](/docs/cloud-compute/access/#reset-the-password) first if you do not have one. SSH keys do not work at the console.

## Open the console

1. In the [dashboard](https://www.coritan.com/dashboard/compute), go to **Cloud Compute** and open the instance.
2. The **Console** tab opens first. The **Display** panel connects on its own and shows the screen once its status reads **Connected**.
3. Click the screen, then type. Your keys go to the instance.

## Use the display toolbar

**Ctrl+Alt+Del**
: Sends that key combination to the instance. Your own computer keeps it for itself when you press it, so use this button instead.

**View only**
: Stops your keyboard and mouse reaching the instance, so you can watch the screen without typing into it by accident. Select it again to type.

**Reconnect**
: Starts a new session and connects again. It reads **New session** while you are connected.

**Fullscreen**
: Fills the browser window with the screen. Select **Exit fullscreen**, or press <kbd>Esc</kbd>, to go back.

> [!NOTE]
> Some older instances still use a serial port as their display, and the console shows a note about it above the screen. Restart the instance once from the header, and the console shows its screen from then on. A `reboot` typed inside the instance does not change its display.

## Read the rest of the tab

The four cards above the display show the instance's size and use:

**vCPU**
: The number of cores, and the share of them in use.

**Memory**
: The memory size, and the share in use.

**Disk**
: The disk size, and the share the host reports as allocated.

**Bandwidth**
: The traffic used this period against the plan's allowance, and the date it resets. [How instance traffic is counted](/docs/cloud-compute/traffic/) explains the figure.

The **Guest** card shows what the QEMU guest agent inside the instance reports: its operating system, kernel and the addresses it sees. The badge reads **Agent running** when the agent answers, and **Agent offline** when it does not. You need the agent to [reset the password](/docs/cloud-compute/access/#reset-the-password), and it lets the instance shut down cleanly when you select **Stop**.

The **Configuration** card shows the virtual hardware: CPU model, storage, host location, template, VM ID, boot order, each disk and network card, and the network settings and user account that cloud-init applies. The password and SSH keys never appear there.

The **Recent tasks** table lists the last eight tasks the host ran for the instance, such as power actions, backups, snapshots and console sessions. **Status** reads `OK` when a task finished, `Running` while it runs, or the error the host gave. Select the refresh button (**Refresh tasks**) to read the list again.

## Result

You see the instance's screen, and you can sign in at it as you would at a physical machine.

## Troubleshooting

`The instance is powered off`
: The instance is stopped. Select **Start** in the header. The console connects once the instance is running.

`Could not connect to the console`
: The session expired before it connected, or the host did not answer. Select **Try again** for a new session. If the message below it says `You are signed out. Sign in again to open the console.`, sign in to the dashboard again first.

`Disconnected`
: The session ended or the connection dropped. Select **Try again** for a new session.

`The guest agent is not responding`
: The instance has no QEMU guest agent, or it is not running. Install it from the console or over SSH. On Ubuntu or Debian, run `sudo apt install qemu-guest-agent`. On AlmaLinux, Rocky Linux or Fedora, run `sudo dnf install qemu-guest-agent`. Then run `sudo systemctl start qemu-guest-agent`.

`No public address`
: The instance has no public IP address, so you can reach it only through this console. Select **Open Network** and attach a floating IP, as [Manage an instance's addresses and names](/docs/cloud-compute/networking/) describes.

## Related

- [Connect to an instance over SSH](/docs/cloud-compute/connect-to-an-instance/) once it is on the network.
- [Repair an instance in rescue mode](/docs/cloud-compute/rescue-mode/) when it does not boot at all.
- [Manage an instance's password, SSH keys and hostname](/docs/cloud-compute/access/) to reset the password or change the keys.

## With the API

`GET /api/v1/client/vps/{uuid}/console` starts a console session on the instance's host.

```bash
curl https://api.coritan.com/api/v1/client/vps/$INSTANCE_UUID/console \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "vnc_ws": "/ws/vps/vnc/5b0c2f7e-8a31-4d2b-9f4e-2a7c1d9e6b10",
  "vnc_session": "q3Vx…",
  "vnc_password": "Zk2p…",
  "expires_in": 120,
  "display": "vga"
}
```

Within `expires_in` seconds, connect a VNC client that speaks WebSocket, such as noVNC, to the socket below. Pass your access token and the session in the query string, and answer the VNC password prompt with `vnc_password`.

```text
wss://api.coritan.com/ws/vps/vnc/<instance uuid>?token=<access token>&session=<vnc_session>
```

Ask for a new session for every connection, as the dashboard does. `display` is `serial` while the instance still uses its serial port as its screen; restart it with the `reboot` power action to give it a graphics display. When the socket cannot connect, it closes with one of these codes:

`4001`
: The token is not a valid access token.

`4003`
: The instance is not on your account, or it is suspended or being moved.

`4004`
: The session is missing or expired, or the host's console is not available. Ask for a new session.

`4029`
: You already have too many consoles open. Close one and try again.

When the host cannot start a console, `GET /console` answers `400` with a message that starts `Console unavailable`.

`GET /api/v1/client/vps/{uuid}/config` returns the virtual machine's configuration with the password and SSH keys removed. `config` holds `cores`, `memory` (in MiB), `name`, `ostype`, `boot`, `agent`, `disks` and `nics` (keyed by device, such as `scsi0` or `net0`), and `cloud_init`, the settings cloud-init applies, such as `ipconfig0`, `ciuser` and `nameserver`. The response also carries `vmid`, `rescue_mode` and `rescue_iso`.

`GET /api/v1/client/vps/{uuid}/guest` asks the guest agent. `agent_online` is `true` when it answered, and `os_info` and `network_interfaces` then hold what it reported. When a question fails, `agent_error`, `os_error` or `network_error` says why, such as `VM is not running` or `qemu-guest-agent not responding`.

`GET /api/v1/client/vps/{uuid}/tasks` returns the host's recent tasks for the instance. Send `limit` for how many: the default is 50 and the most is 100.

`type`
: What the task did, such as `qmstart`, `qmshutdown`, `qmsnapshot`, `vzdump` for a backup or `vncproxy` for a console session.

`status`
: `OK` when the task finished cleanly, and the error when it failed. It is absent while the task runs.

`starttime`, `endtime`
: When the task started and finished, in Unix seconds.

`upid`
: The host's ID for the task.

While we move the instance to another host, `/config`, `/guest` and `/tasks` answer `409` with `Instance is migrating`.

## API

- `GET /api/v1/client/vps/{uuid}/console`: Mint a VNC console session (WebSocket path + RFB password) (https://www.coritan.com/docs/api/reference/client/cloud-compute/#op-get-api-v1-client-vps-uuid-console)
- `GET /api/v1/client/vps/{uuid}/config`: Get instance config (https://www.coritan.com/docs/api/reference/client/cloud-compute/#op-get-api-v1-client-vps-uuid-config)
- `GET /api/v1/client/vps/{uuid}/guest`: Get guest info (https://www.coritan.com/docs/api/reference/client/cloud-compute/#op-get-api-v1-client-vps-uuid-guest)
- `GET /api/v1/client/vps/{uuid}/tasks`: Get instance tasks (https://www.coritan.com/docs/api/reference/client/cloud-compute/#op-get-api-v1-client-vps-uuid-tasks)