Skip to content

BisectHosting Integration

QS-Bridge integrates with BisectHosting's Starbase API for server lifecycle management — start, stop, restart, and wipe game servers directly from the admin panel.

Overview

The primary deployment target for QS-Bridge is community server operators running multiple game servers under a single BisectHosting account. The Starbase API provides programmatic control over server lifecycle, eliminating the need for SSH access or manual panel visits.

sequenceDiagram
    participant Panel as Admin Panel
    participant GW as API Gateway
    participant BH as BisectHosting Starbase API

    Panel->>GW: POST (Click "Restart")
    GW->>GW: Validate JWT + Role, Rate limit
    GW->>BH: HTTPS request
    BH->>BH: Server restarts
    BH-->>GW: 200 OK
    GW-->>Panel: 200 OK (Toast: "Restarted")

How It Works

One Account → Many Servers

The BisectHosting API key maps to one account that owns all servers. Each game server is identified by a UUID assigned by BisectHosting, stored in the ServerRegistry.hosting_id column.

ServerRegistry Column Example Purpose
server_id server-01 QS-Bridge internal identifier
hosting_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 BisectHosting server UUID
status Running Current server state

API Key Security

The API key is stored server-side only in the gateway's .env file:

# panel/api/.env
BISECT_API_KEY=your-starbase-api-key

The React panel never sees or transmits the API key. All lifecycle actions go through the API gateway, which:

  1. Validates the admin's JWT session
  2. Checks admin role level (≥ Admin required)
  3. Enforces rate limiting (1 action per server per 60 seconds)
  4. Proxies the request to BisectHosting with the server-side API key

Available Actions

Action Panel Button API Route BisectHosting Endpoint
Start ▶ Start POST /api/hosting/start POST /servers/{id}/start
Stop ⏹ Stop POST /api/hosting/stop POST /servers/{id}/stop
Restart 🔄 Restart POST /api/hosting/restart POST /servers/{id}/restart
Wipe 🗑 Wipe POST /api/hosting/wipe POST /servers/{id}/wipe

Wipe Confirmation

The Wipe action requires a double confirmation in the panel:

  1. Click "Wipe" → confirmation dialog appears
  2. Type the server name to confirm → dialog enables the "Wipe" button
  3. Click "Wipe" → action executes

This prevents accidental data loss.

Rate Limiting

To prevent API abuse and protect against accidental rapid-fire actions:

Limit Value
Per-server cooldown 60 seconds between lifecycle actions
Per-admin cooldown None (can act on different servers concurrently)
Scope Per (server_id, action) pair

If an action is rate-limited, the gateway returns 429 Too Many Requests with a Retry-After header.

Panel UI

The Servers page (/servers) displays a grid of server cards. Each card shows:

  • Server name and region
  • Status badge (Online / Offline / Starting / Stopping)
  • Player count (12/64)
  • Uptime
  • Lifecycle action buttons
graph TD
    subgraph ServerCard["🟢 Server Alpha — US-East"]
        Info["Players: 12/64 | Uptime: 3d 14h"]
        Actions["▶ Start | ⏹ Stop | 🔄 Restart | 🗑 Wipe"]
    end

Gateway Routes

// panel/api/routes/hosting.ts

// All routes require JWT auth + AdminRole >= Admin
router.post('/api/hosting/start',   rateLimit, hostingAction('start'));
router.post('/api/hosting/stop',    rateLimit, hostingAction('stop'));
router.post('/api/hosting/restart', rateLimit, hostingAction('restart'));
router.post('/api/hosting/wipe',    rateLimit, hostingAction('wipe'));

// Server command (RCON) — routes exist, panel UI pending
router.post('/api/hosting/command', rateLimit, hostingCommand);

Setup Steps

1. Get Your API Key

  1. Log in to your BisectHosting control panel
  2. Navigate to Account Settings → API
  3. Generate a new API key with server management permissions
  4. Copy the key

2. Find Your Server UUIDs

  1. In the BisectHosting control panel, open each server
  2. Note the server UUID from the URL or server details page
  3. You'll need one UUID per game server

3. Configure the Gateway

# panel/api/.env
BISECT_API_KEY=your-api-key-here

4. Map Servers

When a game server starts with libqsbridge.so, it registers itself in ServerRegistry. Set the hosting_id column to the BisectHosting UUID:

UPDATE server_registry
SET hosting_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
WHERE server_id = 'server-01';

Or set it via environment variable:

QSB_HOSTING_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Affiliate Partnership

QS-Bridge includes a BisectHosting affiliate integration. Users who sign up through the wiki or panel referral links support the project:

  • Wiki sidebar: BisectHosting banner with referral link
  • Panel footer: "Powered by BisectHosting" with referral link