# Live console

Watch the desktop of a sandbox live in your browser and take over the mouse and keyboard when you need to – like the console of a virtual machine. The live console is part of [Desktop & Computer Use](https://sandbox.wbx.cz/docs/sandboxes/desktop.md) (beta).

**Before you start.** The console needs a running sandbox from the `desktop` template and the Desktop & Computer Use feature enabled for your team – it is a beta feature that we turn on per team on request. Without it there is no *Desktop* button and the template is not offered. What is on the desktop and how to start programs there is in [Desktop environment (XFCE)](https://sandbox.wbx.cz/docs/sandboxes/desktop-environment.md).

## Open the console

1. On the *Sandboxes* page, start a sandbox from the `desktop` template (*Start a sandbox* → Template `desktop`), or let your agent create one.
2. Click *Desktop* on the card of the running sandbox.
3. The page connects within a second or two and shows the screen. The status next to the buttons says *Live* while the picture is streaming.

The console is a continuous stream of the screen (VNC, shown in your browser with noVNC) – the picture changes as soon as something on the desktop does, not once a second. It is scaled to fit the window and the page does not scroll; *Fullscreen* uses your whole screen (Esc leaves it).

## Watching and taking control

| Control | What it does |
| --- | --- |
| **Watching** (default) | You see everything the agent does. Your mouse and keyboard are not passed to the desktop, so you cannot get in the agent's way by accident. |
| *Take control* | The console switches to control mode: click into the picture and the mouse and keyboard work directly on the desktop. While you are in control the agent's actions are refused with `409` `human_in_control` – it can still take screenshots and wait for you. |
| *Release control* | Hands the desktop back to the agent; the console goes back to watching. |
| *Keys* | Shortcuts your browser keeps for itself: `Ctrl+W`, `Ctrl+T`, `Ctrl+N`, `Ctrl+Tab`, `Ctrl+Shift+Tab`, `Alt+Tab`, `Alt+F4`, `Super`, `Esc` and `F11` – they go to the desktop instead of closing your browser tab. Works only while you are in control. |
| *Clipboard* | Text copied on the desktop appears in the box. While you are in control, *Send to desktop* puts the text from the box into the desktop clipboard – paste it there with `Ctrl+V`. |
| *Fullscreen* | Shows the desktop on your whole screen. |
| *Reconnect* | Appears when the connection closed (the sandbox fell asleep or ended, or the network dropped) and opens it again. |

Control goes back to the agent on its own after **2 minutes without your input** or after **10 minutes** in total (a longer time, up to 60 minutes, can be set through the API with `ttl_s`). Closing the tab while you are in control hands it back too. Taking and releasing control is recorded in the *Access log* of the portal.

Your agent sees the same thing through the API: `GET /v1/sandboxes/{id}/computer/status` returns `"controller": "human"` and `controller_until` while you are in control. A good agent waits and takes a screenshot instead of retrying blindly – see [Desktop & Computer Use](https://sandbox.wbx.cz/docs/sandboxes/desktop.md#control).

## Tips

- **Let the agent work, step in when it is stuck.** Watch first; take control only to solve what the agent cannot – a CAPTCHA you are allowed to solve, a login with your own credentials, a dialog it misreads – then release control and let it continue.
- **Typing non-Latin text.** The clipboard carries text in Western European characters reliably; other characters (for example Czech diacritics) may arrive as `?`. Type such text directly with the keyboard while in control.
- **Several people can watch.** Members of the team can open the console of the same sandbox at the same time (up to 4 consoles per sandbox). Control belongs to people as a whole – while anyone has it, the agent waits – so agree who types.
- **Watching costs nothing extra.** The sandbox is billed by its vCPU and memory while it runs, as always; the console itself is free and does not keep an idle sandbox awake – your input while in control does.

## Limits

| What | Limit |
| --- | --- |
| Open consoles | 4 per sandbox and 8 per team |
| One connection | at most 1 hour – the page then reconnects by itself |
| Console page | stops after 30 minutes; *Resume* (or reloading the page) continues |
| Control by a person | 10 minutes by default (up to 60 through the API); ends after 2 minutes without input |

## How it is protected

- No port of the sandbox is opened for the console – not to the internet and not inside the sandbox. The VNC server runs inside the sandbox as the desktop user and talks to our servers only through the sandbox agent.
- The browser connects over a WebSocket on the portal's own address with a one-time ticket valid for 60 seconds, issued only to a signed-in member of the team that owns the sandbox, and only for the same website.
- While you are only watching, the VNC server inside the sandbox runs in view-only mode – input is ignored there, not just in your browser.
- API keys and MCP connections cannot open the console or act as a person; they are always the agent.

## Troubleshooting

- ***Live console unavailable – showing screenshots*** – The page could not open the live console and shows screenshots refreshed about once a second instead (you can still take control, click and type). The usual cause is a sandbox created from an older build of the `desktop` template that has no VNC server – start a new desktop sandbox. If it happens with a new sandbox too, your network or a browser extension may be blocking WebSockets; the browser's developer console shows the reason in lines starting with `[desktop]`.
- ***The sandbox is not running* / *Sandbox is asleep*** – Watching does not wake a sandbox. Wake it up on the *Sandboxes* page (*Wake up*) or run any command, then click *Reconnect*. See [Sleep and wake](https://sandbox.wbx.cz/docs/sandboxes/sleep.md).
- ***Control went back to the agent*** – You did not touch the mouse or keyboard for 2 minutes, the control time ran out, someone released control in another tab, or the sandbox restarted. Click *Take control* again.
- **The keyboard does nothing** – Take control first, then click into the picture so it has the focus. Shortcuts your browser keeps for itself go through *Keys*.
- **No *Desktop* button** – The sandbox is not from the `desktop` template, it is not running, or Desktop & Computer Use is not enabled for your team.

Source: https://sandbox.wbx.cz/docs/sandboxes/console
