Use a sandbox desktop over RDP
This guide creates a sandbox with a graphical desktop, drives it from the SDK,
and opens it in an RDP client. You need tritonctl signed in to your cloud,
and the desktop feature gate, which your operator turns on. The desktop
template has an XFCE desktop and the Firefox ESR browser.
Step 1: Create a desktop sandbox
tritonctl sandbox create --name desk --template desktop
Step 2: Open the desktop in an RDP client
tritonctl sandbox rdp desk
The command listens on local port 13389 and runs until you press Ctrl-C.
It prints the user name, the sandbox's RDP password, and an xfreerdp command
line. The password is set once when the sandbox is created and stays the same
for the sandbox's life, so every rdp call prints the same one. Treat it as a
secret.
On stderr it prints the SHA-256 fingerprint of the sandbox's own certificate.
Connect any RDP client to localhost:13389, and check the certificate
fingerprint against the one printed. Use --local to pick another local
port.
--bind with an address other than 127.0.0.1 lets anyone who can reach
that address try the login.
Drive a desktop from the SDK
The SDK creates its own desktop sandbox and sends screenshots and input. Each
call runs the sbx-desktop tool in the guest over exec:
from triton_sandbox import Sandbox
sbx = Sandbox.create(template="desktop")
open("screen.png", "wb").write(sbx.desktop.screenshot())
sbx.desktop.left_click(200, 300)
sbx.desktop.type("hello")
sbx.desktop.key("Return")
type sends printable ASCII, newline, and tab, on a US keyboard layout.
To watch the desktop live, use tritonctl sandbox rdp. The SDK's
rdp_tunnel() (rdpTunnel() in TypeScript) forwards guest TCP port 3389,
where nothing listens, so an RDP client gets no connection through it.
If the desktop does not open
| Symptom | Cause | Fix |
|---|---|---|
403 FeatureDisabled naming desktop | The desktop is not on for your tenant. | Ask your operator. |
| New RDP connections hang | A stuck RDP connection blocks new ones until it times out. | Wait for it to time out. Exec and port-forward still work. |
desktop.stream_url() raises NotImplementedException | The live view is RDP only. | Use tritonctl sandbox rdp. |