Skip to main content
ubuntu-vnc is a desktop-enabled sandbox image for browser automation and computer-use agents. It starts XFCE, TigerVNC, and Firefox for you. This guide builds on Sandboxes. If you already installed the Python SDK and authenticated with tl login, you can start a desktop sandbox with a single call. Start with a sandbox client. 
from tensorlake.sandbox import SandboxClient

client = SandboxClient()

​
Spawn an ubuntu-vnc Sandbox

Use image="ubuntu-vnc" when you want a full desktop instead of a shell-only environment. 
with client.create_and_connect(image="ubuntu-vnc") as sandbox:
    print(sandbox.sandbox_id)
You still get a normal Sandbox object back, so desktop automation fits alongside run(), file operations, PTY sessions, and snapshots.

​
Capture Screenshots

Attach to the desktop and save a screenshot as a PNG. 
from pathlib import Path

with client.create_and_connect(image="ubuntu-vnc") as sandbox:
    with sandbox.connect_desktop(password="tensorlake") as desktop:
        Path("sandbox-desktop.png").write_bytes(desktop.screenshot())

​
Send Mouse and Keyboard Input

Once you are connected, you can drive the desktop with mouse and keyboard events. 
import time

with client.create_and_connect(image="ubuntu-vnc") as sandbox:
    with sandbox.connect_desktop(password="tensorlake") as desktop:
        desktop.press(["ctrl", "alt", "t"])
        time.sleep(1.0)
        desktop.type_text("echo docs-test > /tmp/desktop-test.txt")
        desktop.press("enter")

    result = sandbox.run(
        "bash",
        ["-lc", "cat /tmp/desktop-test.txt"],
    )
    print(result.stdout.strip())  # docs-test
The Desktop object also gives you move_mouse(), click(), double_click(), scroll(), key_down(), key_up(), and type_text().

​
Reconnect to an Existing Sandbox

If a sandbox is already running, connect to it by ID and attach to the desktop without creating a new VM. 
from pathlib import Path

sandbox_id = "your-running-sandbox-id"

with client.connect(sandbox_id) as sandbox:
    with sandbox.connect_desktop(password="tensorlake") as desktop:
        Path("existing-sandbox.png").write_bytes(desktop.screenshot())
Using with client.connect(...) as sandbox: only closes the client connection when the block exits. It does not terminate the running sandbox. connect_desktop() goes through the authenticated sandbox proxy, so you do not need to expose port 5901. The current managed ubuntu-vnc image uses tensorlake as its VNC password.