RustDesk Manager

A self-hosted admin panel that aggregates machines from multiple isolated RustDesk (hbbs) servers into one interface.

Architecture

┌─────────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   Admin Browser     │────▶│  Central Server  │◀────│  hbbs sync agent │
│  (admin panel UI)   │     │  FastAPI + React  │     │  (on each CT)    │
└────────┬────────────┘     │  Docker :8080     │     └──────────────────┘
         │ localhost:19999  └──────────────────┘
         ▼
┌─────────────────────┐
│  Local Launch Agent │
│  (on admin's PC)    │
└─────────────────────┘

Quick Start

1. Deploy the central server

git clone <repo>
cd rustdesk-manager

# Set a strong password
export ADMIN_PASSWORD=your-strong-password
export SECRET_KEY=$(openssl rand -hex 32)

docker compose up -d

Open http://your-server:8080 — log in with admin / your password.

2. Add a company

1. Click Add Company in the top-right
2. Fill in: company name, HBBS host, HBBR host, and optionally the public key
3. Choose a color for easy identification

3. Get a sync token

1. Click the gear icon next to your company in the sidebar
2. Click Generate New — copy the token (shown only once!)
3. Note the install command shown below the token

4. Install the sync agent on each RustDesk CT

SSH into the machine running hbbs and run:

# Download agent files from the server
curl -O http://your-server:8080/agent/hbbs_agent.py
curl -O http://your-server:8080/agent/install.sh

# Install with your settings
CENTRAL_URL=http://your-server:8080 \
SYNC_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
bash install.sh

The agent will start syncing immediately. Machines appear in the admin panel within 30 seconds.

5. Install the local launch agent on your computer

cd launcher
pip install flask flask-cors
python main.py

Keep this running. Click Connect on any machine to launch RustDesk directly.

For permanent installation, see launcher/README.md.

---

Project Structure

rustdesk-manager/
├── backend/              FastAPI application
│   ├── main.py           App entrypoint, auth, seed data
│   ├── models.py         SQLAlchemy models
│   ├── database.py       DB engine + session
│   ├── routers/
│   │   ├── companies.py  CRUD for companies
│   │   ├── machines.py   List all machines
│   │   ├── sync.py       Sync endpoint + token generation
│   │   └── connect.py    Connect endpoint
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/             React 18 + Vite + TypeScript + Tailwind
│   ├── src/
│   │   ├── App.tsx       Main app + login
│   │   ├── api.ts        API client + helpers
│   │   └── components/   Sidebar, MachinesTable, modals
│   ├── package.json
│   └── vite.config.ts
├── agent/                hbbs sync agent
│   ├── hbbs_agent.py     Reads hbbs DB, POSTs to central server
│   ├── install.sh        Systemd service installer
│   └── README.md
├── launcher/             Local launch agent
│   ├── main.py           Flask HTTP server on localhost:19999
│   ├── build.sh          PyInstaller build script
│   └── README.md
├── Dockerfile            Multi-stage: builds React → copies into Python image
├── docker-compose.yml
└── data/                 SQLite database (created automatically)

---

API Reference

All /api/* endpoints require HTTP Basic auth (admin / ADMIN_PASSWORD).
The /api/sync endpoint uses Bearer token auth instead.

Method	Endpoint	Description
GET	/api/companies	List all companies
POST	/api/companies	Create company
PUT	/api/companies/{id}	Update company
DELETE	/api/companies/{id}	Delete company
GET	/api/companies/{id}/machines	List machines for a company
POST	/api/companies/{id}/sync-token	Generate sync token
GET	/api/machines	List all machines
POST	/api/sync	Receive machine list (Bearer token auth)
POST	/api/connect	Get launch payload for a machine
GET	/api/stats	Total companies + machines count

---

Environment Variables

Variable	Default	Description
ADMIN_PASSWORD	admin	HTTP Basic auth password
SECRET_KEY	changeme-...	Application secret key
DB_PATH	/app/data/db.sqlite	SQLite database path

---

Development

# Backend
cd backend
pip install -r requirements.txt
DB_PATH=./dev.sqlite ADMIN_PASSWORD=dev uvicorn main:app --reload

# Frontend (in another terminal)
cd frontend
npm install
npm run dev

Frontend dev server at http://localhost:5173 proxies /api to http://localhost:8000.

---

Notes

• IP display: hbbs stores IPs as ::ffff:1.2.3.4. The UI automatically strips the IPv6 prefix.
• Last seen: Uses created_at from the hbbs database (first registration time). The OSS version of hbbs does not record live connection timestamps.
• Sync token: Stored in the database. Generate a new one to revoke the old one (old tokens remain valid — delete them from the DB if needed).
• No online/offline status: hbbs OSS does not write connection state to the database. Only "Last seen" (registration time) is shown.