#Servers
In V8 a "server" is an OSS panel linked to an organization. Central keeps only a link record. Everything else is read live. V8 requirement R5
#Connecting an existing server
User provides: server name, panel (API) address, Central key.
| Check | How (OSS side exists) | Failure → message |
|---|---|---|
| Address format | https URL. Normalise to the API base (https://api.<host>/api), no internal addresses (resolve DNS and block private/loopback/metadata IPs) | 422 "Enter the panel's https address" |
| Reachability | GET /api/health (no auth, own 60/min limit) → status: ok OSS API | "We couldn't reach this panel" (timeout / DNS / TLS) |
| Key valid | Authenticated call with Authorization: Bearer sv_central_…, e.g. GET /api/auth/me → machine admin user OSS API | 401 → "This Central key isn't valid or was turned off on the panel" |
| OSS version | health.version (may be null) against Central's minimum Open question | "This panel is too old. Update it to vX.Y" |
| Already connected | Same panel already linked (here or in another organization) Missing | "This server is already connected" |
| Plan limit | Servers in use < allowed_servers V7 only | 403 PLAN_LIMIT_REACHED + upgrade |
| Subscription expired | V7 only | "Renew your subscription to add servers" |
Example: the OSS calls behind "Connect server" (real OSS API)
# 1. On the OSS panel (admin session) — creates or rotates the key, shown once
POST https://api.<panel-host>/api/central/enable
201 {"central_token": "sv_central_…", "message": "…"}
# 2. Central backend — reachability + version (no auth)
GET https://api.<panel-host>/api/health
200 {"health": {"status": "ok", "version": "1.0.14"}}
# 3. Central backend — key check (signs in as the machine admin)
GET https://api.<panel-host>/api/auth/me
Authorization: Bearer sv_central_…
200 {"user": {"username": "central", "is_admin": true, …}}
401 {"message": "Unauthenticated."} # wrong / revoked / rotated key
# 4. First data for Server Details
GET https://api.<panel-host>/api/server/facts
200 {"facts": {"hostname": "srv1", "os": "Ubuntu 24.04 LTS", "public_ip": "…", "cpu": {…}, …}}Getting the key: on the OSS panel, an admin opens Admin → Central and clicks Connect. POST /central/enable returns central_token once. Enabling again rotates it, and the old key stops working at once. OSS API
The demo uses sm_<hex> "Server Management Key" in the same wizard. The real format is sv_central_…. Demo UI only Conflict (cosmetic; follow OSS)
#Link record (proposal, Q1 open)
| Field | Why |
|---|---|
organization_id | Ownership |
name | Display (Central-side label) |
api_url | Where to call |
central_token (encrypted) | Auth to OSS. Never returned to the browser |
status + last_seen_at + last_error | List and dashboard without calling every server each time |
oss_version | Compatibility |
public_ip, os, hostname (cached copy) | The list must show IP/OS when the server is offline. Conflicts with "store minimum" Open question |
provider_id / instance_id (if created by Central) | Link to the provider VPS |
connected_by, connected_at | Audit |
#States
| State | Meaning | Detected by |
|---|---|---|
connecting | Being created/installed by Central (provider flow) | Central job |
online | Health ok and key accepted | Health + auth ping |
offline | No answer / timeout | Health check |
unauthorized | 401: key revoked or rotated on the panel | Any call |
outdated | Version below minimum | Health |
error | Other failure | OSS 5xx |
A background job (Horizon) refreshes status every few minutes, so lists don't wait on servers. Missing Assumption interval.
#Remove / disconnect
Removing a server means disconnecting it from Central. The server and its sites keep running. V8 requirement (no server deletion in OSS)
Destroying a VPS created through a provider is a separate, explicit action (provider API), and only if the backend supports it Open question.
#Edge cases
| Case | Behaviour |
|---|---|
| Invalid key | 401 on connect → field error. On an existing server → state unauthorized, banner "Reconnect with a new key" (paste the new key, keep the same server record) |
| Offline server | Server Details shows the "unreachable" state with Retry and last-seen time. Disconnect still works |
| Already connected | 409/422 with the organization name, only if the user is a member of it, otherwise a neutral message |
| Version mismatch | Connect refused (too old) or allowed with a warning (newer than tested) Open question |
| Revoked key | Same as invalid key, detected on any call |
| Connection failure mid-action | OSS 5xx carries reference. Show it ("Reference: …") so support can find the panel log |
| Panel updating | /health answers but the version changes. Retry |
| Key rotated on the panel | All calls 401 until the user pastes the new key |