WBX Sandbox
Sandboxes

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 (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).

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

ControlWhat 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 controlThe 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 controlHands the desktop back to the agent; the console goes back to watching.
KeysShortcuts 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.
ClipboardText 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.
FullscreenShows the desktop on your whole screen.
ReconnectAppears 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.

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

WhatLimit
Open consoles4 per sandbox and 8 per team
One connectionat most 1 hour – the page then reconnects by itself
Console pagestops after 30 minutes; Resume (or reloading the page) continues
Control by a person10 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.
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.