Skip to content

Self-Hosting XRXP

XRXP is designed to be self-hosted by labs, studios, and research teams.

What you need to run

Minimum stack:

  • PostgreSQL
  • Redis
  • REST API
  • WebSocket ingestion service
  • Dashboard

The repository already includes a development compose file for PostgreSQL, Redis, API, and WebSocket.

Quick local deployment

1. Start infrastructure and backend services

docker compose -f docker-compose.dev.yml up -d db redis api websocket

2. Start the dashboard

pnpm install
pnpm --filter @xrxp/dashboard dev

3. Open the system

  • Dashboard: http://localhost:5174
  • API health: http://localhost:8080/health
  • WebSocket: ws://localhost:8081

First boot

On a fresh installation:

  1. open the dashboard
  2. go through the first-run setup flow
  3. create the first administrator account
  4. create service tokens for Unity clients and automation

What the compose file already covers

docker-compose.dev.yml starts:

  • PostgreSQL 16
  • Redis 7
  • API container
  • WebSocket container

It also mounts a persistent uploads volume for the API.

For a production-style self-hosted deployment, keep these principles:

  • persistent storage for PostgreSQL, Redis, and uploads
  • stable public URLs for API and WebSocket endpoints
  • TLS in front of browser-facing and device-facing endpoints
  • regular monitoring of queue depth and failed messages
  • separate secrets from checked-in config

Operator checklist

  • Create the first admin account.
  • Create at least one service token.
  • Verify a Unity device can connect and start a session.
  • Verify session data becomes visible in the dashboard.
  • Verify controller and exchange flows on a connected device.

What is live and what is stored

  • Live: WebSocket subscriptions, connected devices, exchange status, controller activity.
  • Stored: sessions, events, users, scenes, device metadata, exchange snapshots.