# Platform Agent

An integrated agent for Jetson and Mobility PC devices that connects Platform IDE to local desktop, workspace, camera, Docker modules, and ROS bridge services.

This project combines the previous `platform-agent`, `autoware-back`, and `nav2-back` roles into one process and one configuration file.

## Features

- KasmVNC remote desktop status, start, and stop
- Workspace file browsing, reading, saving, and image preview
- Docker-based Autoware/Nav2 module listing, logs, start, and stop
- Browser terminal WebSocket
- Camera device listing, MJPEG, and WebRTC sender control
- Unified Autoware/Nav2 ROS bridge control API
- Web settings UI

## Run

```bash
bun install
bun run start
```

Default URL:

```text
http://127.0.0.1:3100
```

Settings UI:

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

KasmVNC iframe:

```text
http://<device-ip>:3100/remote
```

## Install

curl -fsSL https://pub-ca72c40797144462bdb7d200c215d361.r2.dev/studio-files/public/platform-agent/install.sh | sh

Install from a local checkout:

```bash
cd /path/to/agent_v2
sh scripts/install.sh
```

For remote `curl | sh` installs, publish an architecture-specific installer archive and a small bootstrap script. The TUI binary must be built for both `amd64` and `arm64`.

```bash
curl -fsSL https://pub-ca72c40797144462bdb7d200c215d361.r2.dev/studio-files/public/platform-agent/install.sh | sh
```

The default install path is `/opt/platform-agent`.

```bash
PLATFORM_AGENT_DIR=/opt/platform-agent PLATFORM_AGENT_USER=ubuntu sh scripts/install.sh
```

Tailscale settings can be provisioned from your backend instead of asking the installer user to enter auth keys.

```bash
sh scripts/install.sh
```

The default provisioning endpoint is `https://portal-api.autonomystudio.net/api/provision`. Override it with `PLATFORM_PROVISION_URL` when the backend runs somewhere else.

```bash
PLATFORM_PROVISION_URL=https://your-domain/api/provision sh scripts/install.sh
```

In Launcher, open **Platform management** and select **Register** to create a one-time six-digit registration code. Enter the Autonomy Studio account email and that code in the installer. The code expires after five minutes, can be used only once, and is not written to the final install configuration file.

```json
{
  "hostname": "device-hostname",
  "os": "linux",
  "arch": "arm64",
  "kernel": "5.15.0-tegra",
  "distro": "Ubuntu 22.04.5 LTS",
  "device": {
    "hostname": "device-hostname",
    "os": "linux",
    "arch": "arm64",
    "kernel": "5.15.0-tegra",
    "distro": "Ubuntu 22.04.5 LTS"
  }
}
```

The backend response supports these keys. Both camelCase and snake_case are accepted.

```json
{
  "installTailscale": true,
  "tailscaleAuthKey": "tskey-auth-test-autonomy-studio",
  "tailscaleLoginServer": "https://headscale.example.com",
  "tailscaleHostname": "device-hostname",
  "tailscaleExtraArgs": "--accept-routes"
}
```

If `tailscaleAuthKey` is present, `installTailscale` is treated as `true`.

Interactive installs prefer the Bubble Tea TUI. If Go is available on the device, the installer can run the source below with `go run`; otherwise it falls back to shell prompts.

```text
scripts/installer-tui/
```

When shipping prebuilt TUI binaries in a release:

```bash
PLATFORM_INSTALLER_TUI_URL=https://your-domain/platform-agent-installer-tui-linux-{arch} \
sh scripts/install.sh
```

Example TUI binary builds:

```bash
cd scripts/installer-tui
go mod tidy
GOOS=linux GOARCH=amd64 go build -o installer-tui-linux-amd64 .
GOOS=linux GOARCH=arm64 go build -o installer-tui-linux-arm64 .
```

For a noninteractive environment-only install:

```bash
PLATFORM_AGENT_INTERACTIVE=false \
PLATFORM_AGENT_DIR=/opt/platform-agent \
WORKSPACE_ROOT=/home/ubuntu/.caches \
ROS_DOMAIN_ID=0 \
sh scripts/install.sh
```

If you need to force Tailscale settings in a noninteractive install, the existing environment variables still work.

```bash
PLATFORM_AGENT_INTERACTIVE=false \
INSTALL_TAILSCALE=true \
TAILSCALE_AUTH_KEY=tskey-auth-... \
sh scripts/install.sh
```

Install steps are printed with progress output.

Autoware/Nav2 is not selected during install. The unified bridge supports both, and the active target can be changed after install in the Settings UI `ROS Bridge` section or by choosing which ROS bridge module to run. Use `ROBOT_STACK=autoware|nav2` only when you need to force the initial value in a noninteractive install.

## Unified Config

The default config file is `agent.config.json`.

Main sections:

- `server`: agent host, port, and public URL
- `workspace`: workspace root exposed to Platform IDE
- `desktop`: KasmVNC display, web port, and resolution
- `camera`: camera device, signaling URL, and resolution
- `ros`: Autoware/Nav2 stack, ROS_DOMAIN_ID, and bridge URL
- `modules`: module run script paths

Use `AGENT_CONFIG` to override the config file path.

## Platform IDE Compatible API

```text
GET  /health
GET  /api/config
PUT  /api/config

GET  /api/workspace/summary
GET  /api/workspace/tree
GET  /api/workspace/file
GET  /api/workspace/image
POST /api/workspace/file

GET  /api/modules/workspaces
GET  /api/modules/docker-statuses
GET  /api/modules/logs
POST /api/modules/start
POST /api/modules/stop
WS   /api/modules/terminal

GET  /api/camera/status
GET  /api/camera/devices
POST /api/camera/start
POST /api/camera/stop
GET  /api/camera/mjpeg

GET  /api/kasmvnc/status
POST /api/kasmvnc/start
POST /api/kasmvnc/stop

GET  /api/bridge/status
GET  /api/bridge/stack
POST /api/bridge/clear
POST /api/bridge/stop
POST /api/bridge/reset
```

Autoware/Nav2 viewer compatible API:

```text
POST /plan
POST /drive
POST /clear
POST /stop
POST /reset
```

## ROS Bridge

The unified bridge is `ros_bridge/bridge.py`. It uses `ROBOT_STACK=autoware|nav2` or `agent.config.json` `ros.stack` to choose the active target behavior.

Direct run example:

```bash
source /opt/ros/humble/setup.bash
pip install -r ros_bridge/requirements.txt
ROBOT_STACK=autoware ROS_DOMAIN_ID=0 python3 ros_bridge/bridge.py
```

Docker image build examples:

```bash
docker build -f ros_bridge/Dockerfile.autoware -t autoware-ros-bridge ros_bridge
docker build -f ros_bridge/Dockerfile.nav2 -t nav2-ros-bridge ros_bridge
```

## Host Dependencies

Install the minimum agent first, then add optional host dependencies for the features used on each device.

- Common: Bun, Docker
- Remote desktop: KasmVNC, XFCE
- Camera: GStreamer, v4l-utils, python3-gi, websockets
- ROS bridge: ROS2 Humble and message packages for the active stack
- NVIDIA GPU containers: nvidia-container-toolkit or device-specific GPU runtime

## Verify

```bash
bun run typecheck
curl http://127.0.0.1:3100/health
curl http://127.0.0.1:3100/api/config
curl http://127.0.0.1:3100/api/kasmvnc/status
curl http://127.0.0.1:3100/api/bridge/status
```