Connect over VNC

A Tektona sandbox can run a full graphical desktop and stream it to your browser. You don't install or run a VNC server inside the image. Tektona renders the display for you, so the image only needs the desktop and the apps you want to see.

Connect

Open a VNC session to a running sandbox:

tektona vnc <sandbox-id>

This opens a browser tab with the sandbox's desktop. Close the tab to disconnect. See the tektona vnc reference for connecting to several sandboxes at once and the full flag list.

Start the desktop on demand

A sandbox doesn't always have the desktop running. Start it as part of the connect step:

tektona vnc <sandbox-id> --start-desktop

Or manage it directly:

tektona sandbox desktop start <sandbox-id>
tektona sandbox desktop stop <sandbox-id>
tektona sandbox desktop status <sandbox-id>

sandbox desktop start needs an image that ships a desktop: the official desktop-x11 image, an image built from it, or your own image that declares its desktop with a session script. On any other image the command reports an error, because there is nothing to start.

sandbox desktop status prints active when the desktop runs, and inactive when it does not. Use it to make sure a start worked before you connect. It answers on any image: one that ships no desktop reports inactive.

tektona vnc and tektona sandbox screenshot need none of this. They read the sandbox screen itself, which shows the text console when no desktop runs.

Use a desktop template

VNC needs an image that ships a graphical environment. The recommended starting point is tektona/desktop, the template built from Tektona's official X11 desktop image. It includes an X session, a browser, and everything the desktop needs:

tektona sandbox create tektona/desktop --egress-policy tektona/open

See Manage Sandboxes → Choosing a template for the pinning rules.

Building your own desktop image

You can build a custom desktop image instead of using the official one. Two things make this simpler than on most sandbox providers:

• No VNC server to install. You don't bundle or run x11vnc, TigerVNC, noVNC, or any VNC daemon. Tektona provides the streaming layer outside the image, so there's nothing to configure or keep running.
• No X server to start. Tektona configures the virtual graphics and input devices, starts the X server on display :0, and waits for it. Your image only puts things on the screen.

The easiest path is to build from the official desktop image, then add your own apps on top:

FROM ghcr.io/tektona-ai/desktop-x11:0.6.0
RUN apt-get update && apt-get install -y your-gui-app

Push the image to a registry, build a template from it, then create sandboxes from that template. Private images need a registry credential. See Run a Custom Image for that flow.

The session script

To build a desktop image from something other than desktop-x11, add an executable at /etc/tektona/desktop-session. Tektona runs it after the X server is up, so it decides what the desktop looks like: the window manager, the wallpaper, the applications, anything else you want on screen.

FROM your-base-image
RUN apt-get update && apt-get install -y xserver-xorg-core openbox xdotool

COPY desktop-session /etc/tektona/desktop-session
RUN chmod 0755 /etc/tektona/desktop-session

#!/bin/sh
# DISPLAY and HOME are already set. The X server is already running.
exec openbox

The file is also how Tektona knows the image has a desktop. An image without it, and not built from desktop-x11, refuses desktop start.

Two things to get right:

• Stay in the foreground. exec the window manager, or end the script with wait. desktop stop kills the session script and the X server, so a script that returns early leaves its own children behind.
• Install xdotool and xclip. Computer use drives the desktop with them. Without xdotool there is no mouse or keyboard input; without xclip there is no clipboard.

Next