Tools

Private API

Every call is authenticated with a bearer token — the gamehoster-config-apiToken from your local tool configuration, sent as Authorization: Bearer <token>. These routes are read-only and identical across every hoster (they live in common/server/logs-stats.js). As with the sync, a correctly authenticated call returns 200 and anything else — bad token, unknown route, wrong version — returns an identical 404; the routes are versioned under /api/v1/, discovered from /api/version. Files are exposed by timestamp (logs), exact validated name (stats) or validated tree-relative path (game logs) only, so a request can never escape the served directory and there is no path-traversal surface.

GET /api/v1/logs

Lists the Caddy access logs so the client can mirror them. The active log is reported by size only; each rotated file is keyed by its rotation timestamp, never its name — so the server can't influence where the client writes, and a newly-appeared timestamp is how the client detects that the active log rotated.

{
  "active": { "size": 12345 },
  "rotated": [
    { "ts": 1784370489663, "size": 67108864 },
    { "ts": 1784514159284, "size": 41943040 }
  ]
}

GET /api/v1/logs/file

Streams the bytes of one access-log file. A Range header is honoured so the client fetches only the tail appended since last time; an immutable rotated file is fetched once, whole. See pull-logs.js.

GET /api/v1/logs/file?which=active HTTP/1.1
Authorization: Bearer <token>
Range: bytes=12345-

GET /api/v1/stats

Lists the server-health day-files and the sampling interval, so the client can mirror them. Files are named <type>-YYYY-MM-DD.log; a past day is frozen and mirrored once, today's file grows.

{
  "interval": 15000,
  "files": [
    { "name": "cpu-2026-07-20.log",    "type": "cpu",    "date": "2026-07-20", "size": 82944 },
    { "name": "memory-2026-07-20.log", "type": "memory", "date": "2026-07-20", "size": 61200 }
  ]
}

GET /api/v1/stats/file

Streams one stat day-file by its exact name, which is validated against <type>-YYYY-MM-DD.log — the only thing that reaches the filesystem, so there is no path-traversal surface. A Range fetches only the growing tail of the current day. See pull-stats.js.

GET /api/v1/stats/file?name=cpu-2026-07-20.log HTTP/1.1
Authorization: Bearer <token>
Range: bytes=61200-

GET /api/v1/stats/now

Returns a single live health snapshot for debugging — the same shape the recorder samples on its interval, but taken on demand and never stored. Counter fields (CPU core times, disk/network bytes) are cumulative; a consumer diffs two snapshots to get a rate. Metrics a host can't report (e.g. disk/network IO off Linux) are null rather than an error. Built by shared/stats.js.

{
  "ts": 1784514159,
  "uptime": 864000,
  "hostname": "vps-1",
  "load": [0.12, 0.09, 0.05],
  "cpu":    { "model": "…", "cores": [ { "user": 0, "nice": 0, "sys": 0, "idle": 0, "irq": 0 } ] },
  "memory": { "total": 0, "used": 0, "available": 0, "free": 0 },
  "disk":   { "path": "/", "total": 0, "used": 0, "free": 0 },
  "diskIo": { "readBytes": 0, "writeBytes": 0 },
  "netIo":  { "rxBytes": 0, "txBytes": 0 }
}

Mirroring Process

The client mirrors both sources the same way, statelessly, deriving everything from what it already has on disk — the counterpart of how the sync diffs hashes. It negotiates the version from /api/version, then:

The download itself lives in the shared toolkit (common/browse/pull-logs.js and common/browse/pull-stats.js), so every hoster mirrors the same way. The mirrored files then feed the static Web Logs and Server Logs browsers. The Game Logs browser mirrors the game-telemetry tree the same way, then builds its overview, per-game and per-instance pages from it.

GET /api/v1/gamelogs

Lists the game-telemetry log tree so the client can mirror it. Every stats and snapshot file is reported by its tree-relative path (<domain>/<game>/gamehoster-processes/<process>/<file>) and size; a past hour is frozen and mirrored once, the current hour's files grow. The path is the only addressing, and the server validates it against the served root, so a request can never escape the tree.

{
  "files": [
    { "path": "game.asteroids.net/asteroids/gamehoster-processes/3f9c1a2b7d4e/stats-2026-07-30-18.jsonl", "size": 48210 },
    { "path": "game.asteroids.net/asteroids/gamehoster-processes/3f9c1a2b7d4e/snapshot-2026-07-30-18.jsonl", "size": 9044 }
  ]
}

GET /api/v1/gamelogs/file

Streams the bytes of one game-log file, addressed by its tree-relative path. A Range header is honoured so the client fetches only the tail appended since last time; a frozen past-hour file is fetched once, whole.

GET /api/v1/gamelogs/file?path=game.asteroids.net/asteroids/gamehoster-processes/3f9c1a2b7d4e/stats-2026-07-30-18.jsonl HTTP/1.1
Authorization: Bearer <token>
Range: bytes=48210-