Open a desktop or private service
You can reach a running box through a private tunnel bound to 127.0.0.1 on your controller. Set $box to your task's handle from raft list. You need an available local port and working host SSH.
Guest services must listen on 0.0.0.0 or the guest's managed network address. A service bound only to guest 127.0.0.1 cannot receive forwarded traffic. Raft does not provide public hosting or reverse forwarding.
Open a web service
Start a server in /workspace, then open the tunnel:
job=$(raft exec "$box" --detach -- python3 -m http.server 8080 --bind 0.0.0.0)
raft forward "$box" --remote 8080 --local 8080In your controller's browser, open http://127.0.0.1:8080. The tunnel stays in the foreground. Press Ctrl+C to close it, then stop this example server with raft cancel "$box" "$job".
Closing a tunnel does not stop the service or extend the box's lifetime. After a box resumes, restart one-off servers and reopen the tunnel. Use an enabled service for automatic startup.
If forwarding fails, check the guest listener and raft logs "$box" "$job". If the local port is occupied, choose another --local port. Forwarding waits up to 30 seconds for the managed guest IPv4 address, not for application readiness.
Open the desktop
raft desktop "$box" --local 6080Open http://127.0.0.1:6080/ in your controller's browser. Voxl is the default viewer and streams H.264 using WebCodecs. Use a browser with H.264 WebCodecs decoding support, and keep the URL on localhost or 127.0.0.1 so it is a secure context. Plain HTTP on a remote IP does not work with WebCodecs.
The desktop runs as developer at 1280×720 on display :99. The command starts the selected streaming service and the shared desktop, then opens a foreground tunnel. Press Ctrl+C to close only the tunnel. Reconnect with the same command without closing guest windows.
Use noVNC instead
If your browser cannot decode Voxl's stream, select noVNC explicitly:
raft desktop "$box" --backend novnc --local 6080Open http://127.0.0.1:6080/vnc.html. Use the noVNC sidebar for text clipboard exchange. Raft does not switch backends automatically.
Both backends show the same desktop. Selecting another backend leaves existing guest windows and streaming services running. To keep both tunnels open, give the second one a different --local port. Voxl listens on guest port 6080; noVNC listens on guest port 6081. Neither requires a viewer password: host SSH authenticates access through the private tunnel. Do not expose either guest port publicly. Voxl keeps its host and origin checks enabled, runs as developer, and roots its file browser at /workspace; desktop audio and microphone are disabled.
To stop one backend, run raft exec "$box" -- systemctl stop raft-desktop-voxl or raft exec "$box" -- systemctl stop raft-desktop-novnc. To stop the desktop and both backends, run raft exec "$box" -- systemctl stop raft-desktop. Stopping or expiring the box also ends the session.
These commands require an image built with both backend services. Updating the CLI does not modify existing images or boxes. Build and pin the updated image, then create a fresh box; a missing backend service fails instead of falling back. If startup fails, inspect raft exec "$box" -- journalctl -u raft-desktop -u raft-desktop-voxl -u raft-desktop-novnc -n 50 --no-pager.