agent/PLATFORM_AGENT_RUNBOOK.md

Platform Agent Runbook

This runbook covers running the Platform Agent on a remote device and connecting a KasmVNC-based remote desktop.

Role

The agent provides these capabilities on the remote platform:

• Start, stop, and inspect a KasmVNC XFCE remote desktop
• Browse, read, and save workspace files
• List, start, stop, log, and connect terminals to Docker modules
• Start and stop the camera WebRTC sender
• List /dev/video* camera devices

Recommended Runtime

Host execution is currently recommended over Docker.

Reasons:

• KasmVNC/XFCE is simpler when attached to the host desktop environment
• Camera and GStreamer stacks are commonly validated on the host
• Adding GStreamer and desktop packages to the Docker image increases image size

Required Host Environment

bun
KasmVNC
XFCE
python3
python3-gi
websockets
GStreamer webrtcbin
v4l-utils
Docker

Check commands:

bun --version
command -v vncserver || command -v kasmvncserver
python3 -c "import websockets, gi"
gst-inspect-1.0 webrtcbin
v4l2-ctl --list-devices
docker ps

Install

cd /home/chyoo/tmp/agent_v2
bun install

bun install installs only JavaScript dependencies. System packages such as KasmVNC, XFCE, and GStreamer must be installed separately.

Run

cd /home/chyoo/tmp/agent_v2
HOST=0.0.0.0 PORT=3100 bun run start

Development run:

cd /home/chyoo/tmp/agent_v2
HOST=0.0.0.0 PORT=3100 bun run dev

Use this URL from the Electron app or browser:

http://<platform-ip>:3100

Main Environment Values

HOST=0.0.0.0
PORT=3100
WORKSPACE_ROOT=/home/ubuntu/.caches

KASMVNC_DISPLAY=:1
KASMVNC_WEB_PORT=6901
KASMVNC_PROTOCOL=http
KASMVNC_INTERFACE=0.0.0.0
KASMVNC_GEOMETRY=1600x900
KASMVNC_DESKTOP=XFCE

CAMERA_ENABLED=true
CAMERA_SIGNALING_URL=ws://SIGNALING_HOST:3000
CAMERA_ROOM_ID=jetson-1
CAMERA_VIDEO_DEVICE=/dev/video0

KasmVNC API

curl http://127.0.0.1:3100/api/kasmvnc/status
curl -X POST http://127.0.0.1:3100/api/kasmvnc/start
curl -X POST http://127.0.0.1:3100/api/kasmvnc/stop

Default command run by the agent:

vncserver :1 -select-de XFCE -geometry 1600x900 -depth 24 -websocketPort 6901 -interface 0.0.0.0

Default KasmVNC web URL:

http://<platform-ip>:6901

API Checks

Health and config:

curl http://127.0.0.1:3100/health
curl http://127.0.0.1:3100/api/config

Workspace:

curl http://127.0.0.1:3100/api/workspace/summary
curl http://127.0.0.1:3100/api/workspace/tree

Camera:

curl http://127.0.0.1:3100/api/camera/devices
curl http://127.0.0.1:3100/api/camera/status
curl -X POST http://127.0.0.1:3100/api/camera/start
curl -X POST http://127.0.0.1:3100/api/camera/stop

systemd Example

[Unit]
Description=Platform Agent
After=network-online.target

[Service]
WorkingDirectory=/home/ubuntu/tmp/agent_v2
ExecStart=/home/ubuntu/.bun/bin/bun run start
Restart=always
Environment=HOST=0.0.0.0
Environment=PORT=3100
Environment=WORKSPACE_ROOT=/home/ubuntu/.caches
Environment=KASMVNC_DISPLAY=:1
Environment=KASMVNC_WEB_PORT=6901
Environment=KASMVNC_PROTOCOL=http
Environment=KASMVNC_INTERFACE=0.0.0.0
Environment=KASMVNC_GEOMETRY=1600x900
Environment=KASMVNC_DESKTOP=XFCE
Environment=CAMERA_ENABLED=true
Environment=CAMERA_SIGNALING_URL=ws://SIGNALING_HOST:3000
Environment=CAMERA_ROOM_ID=jetson-1
Environment=CAMERA_VIDEO_DEVICE=/dev/video0

[Install]
WantedBy=multi-user.target

Register the service:

sudo cp platform-agent.service /etc/systemd/system/platform-agent.service
sudo systemctl daemon-reload
sudo systemctl enable platform-agent
sudo systemctl start platform-agent
sudo systemctl status platform-agent

Logs:

journalctl -u platform-agent -f

Docker Run

Docker compose is available but optional.

cd /home/chyoo/tmp/agent_v2
cp .env.example .env
docker compose up -d --build

Notes:

• Running KasmVNC/XFCE inside a container requires separate desktop session setup
• If KasmVNC and camera integration are already validated on the host, host execution is usually lighter

Troubleshooting

Check ports:

ss -ltnp | grep -E '3100|6901'

Check KasmVNC:

command -v vncserver || command -v kasmvncserver
vncserver -list

Check camera devices:

ls -l /dev/video*
v4l2-ctl --list-devices

Check GStreamer:

gst-inspect-1.0 webrtcbin
gst-inspect-1.0 nvv4l2h264enc