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

bun install
bun run start

Default URL:

http://127.0.0.1:3100

Settings UI:

http://<device-ip>:3100

KasmVNC iframe:

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:

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.

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

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

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.

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.

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.

{
  "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.

{
  "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.

scripts/installer-tui/

When shipping prebuilt TUI binaries in a release:

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

Example TUI binary builds:

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:

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.

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

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:

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:

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:

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

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