# 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

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

Check commands:

```bash
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

```bash
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

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

Development run:

```bash
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:

```text
http://<platform-ip>:3100
```

## Main Environment Values

```bash
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

```bash
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:

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

Default KasmVNC web URL:

```text
http://<platform-ip>:6901
```

## API Checks

Health and config:

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

Workspace:

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

Camera:

```bash
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

```ini
[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:

```bash
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:

```bash
journalctl -u platform-agent -f
```

## Docker Run

Docker compose is available but optional.

```bash
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:

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

Check KasmVNC:

```bash
command -v vncserver || command -v kasmvncserver
vncserver -list
```

Check camera devices:

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

Check GStreamer:

```bash
gst-inspect-1.0 webrtcbin
gst-inspect-1.0 nvv4l2h264enc
```