System API

Health checks and system resource monitoring for the Lamaste droplet.

In Plain English

The system API provides two things: a simple health check that confirms the panel server is running, and a statistics endpoint that reports CPU usage, memory, disk space, and how long the server has been up. The management dashboard uses the stats endpoint to display real-time system resource information.

Authentication

The health endpoint (GET /api/health) does not require mTLS authentication. It is publicly accessible to any client that can reach the panel server. This allows external monitoring tools and the provisioning process to verify the panel is running without needing a client certificate.

The system stats endpoint (GET /api/system/stats) requires a valid mTLS client certificate and a completed onboarding. Admin certificates and agent certificates with the system:read capability can access it. See the API Overview for details.

Endpoints

GET /api/health

A lightweight health check that confirms the panel server is running and responding to requests. Returns the current version number read from package.json.

This endpoint has no onboarding guard — it is accessible at any point in the server's lifecycle. It is useful for monitoring and for the provisioning step that verifies the panel is running.

Request:

No request body.

# No client certificate required
curl -sk https://203.0.113.42:9292/api/health | jq

Response (200):

{
  "status": "ok",
  "version": "0.1.0"
}

Field	Type	Description
status	string	Always "ok" if the server is responding
version	string	Panel server version from package.json (falls back to "0.0.0")

This endpoint has no error cases — if the server is running, it returns 200.

---

GET /api/system/stats

Returns current system resource usage. The data is gathered using the systeminformation library and cached for 2 seconds to prevent excessive system calls when multiple clients poll simultaneously.

Request:

No request body.

curl -s --cert client.p12:password \
  https://203.0.113.42:9292/api/system/stats | jq

Response (200):

{
  "cpu": {
    "usage": 12.5,
    "cores": 1
  },
  "memory": {
    "total": 536870912,
    "used": 268435456,
    "free": 268435456
  },
  "disk": {
    "total": 26843545600,
    "used": 5368709120,
    "free": 21474836480
  },
  "uptime": 432000
}

Field	Type	Unit	Description
cpu.usage	number	Percent	Current CPU utilization (0-100), rounded to one decimal
cpu.cores	number	Count	Number of CPU cores
memory.total	number	Bytes	Total physical RAM
memory.used	number	Bytes	Used RAM
memory.free	number	Bytes	Free RAM
disk.total	number	Bytes	Total disk space on root filesystem
disk.used	number	Bytes	Used disk space on root filesystem
disk.free	number	Bytes	Free disk space on root filesystem
uptime	number	Seconds	System uptime since last boot

Example values for a typical 512MB droplet:

Metric	Typical Value	Human-Readable
memory.total	536870912	512 MB
memory.used	260046848	~248 MB
disk.total	26843545600	25 GB
cpu.cores	1	1 vCPU
uptime	432000	5 days

Errors:

Status	Body	When
500	{"error":"Failed to retrieve system stats"}	systeminformation library call failed
503	{"error":"Onboarding not complete","onboardingStatus":"FRESH"}	Onboarding has not finished

---

POST /api/system/update

Triggers a background update of the Lamaste server to the specified version. The panel runs sudo lamaste-priv self-update <version>; the root-owned helper validates the version (MAJOR.MINOR.PATCH) and starts npx @lamalibre/create-lamaste@<version> --yes — the installer's redeploy path — in a transient systemd unit two seconds later. The transient unit keeps the update alive while the installer stops and restarts the panel; the delay lets this response reach the client first. The panel passes only the version: it never writes a script for root to run.

Authentication: Admin-only. Agent certificates cannot trigger updates.

Request:

{
  "version": "1.0.43"
}

Field	Type	Required	Description
version	string	Yes	Target version to update to (e.g., "1.0.43")

curl -s --cert client.p12:password \
  -X POST -H 'Content-Type: application/json' \
  -d '{"version":"1.0.43"}' \
  https://203.0.113.42:9292/api/system/update | jq

Response (202):

{
  "ok": true,
  "message": "Update to create-lamaste@1.0.43 initiated. The panel will restart shortly."
}

The 202 status indicates the helper has started the update unit (lamalibre-lamaste-update-<random>) and the update is running in the background. The panel server will restart as part of the update process, so the client should expect the connection to drop and poll /api/health to detect when the new version is running.

Errors:

Status	Body	When
400	{"error":"Validation failed","details":{"issues":[...]}}	Missing or invalid version field
403	{"error":"Insufficient certificate scope"}	Non-admin certificate
500	{"error":"Could not start the update: <helper error>"}	lamaste-priv could not start the update unit (e.g. helper missing — re-run create-lamaste)
503	{"error":"Onboarding not complete","onboardingStatus":"FRESH"}	Onboarding has not finished

---

POST /api/agents/plugins/report

Accepts a plugin capability report from an agent. Called by lamaste-agent update to inform the server about plugins the agent has enabled. The server merges the reported capabilities into the valid capabilities set so they can be assigned to agents.

Authentication: mTLS (admin or agent certificate).

Request:

{
  "plugins": [
    {
      "name": "sync",
      "version": "0.1.0",
      "capabilities": ["sync:connect"]
    }
  ]
}

Field	Type	Required	Description
plugins	array	Yes	List of enabled plugins
plugins[].name	string	Yes	Plugin name from manifest
plugins[].version	string	Yes	Plugin version
plugins[].capabilities	array	No	Capability strings (defaults [])

Response (200):

{
  "ok": true,
  "merged": 1
}

Field	Type	Description
ok	boolean	Always true on success
merged	number	Number of unique capabilities merged

---

Caching Behavior

The stats response is cached for 2 seconds. Multiple requests within the cache window return the same data without querying the operating system again. This prevents performance degradation when the dashboard polls frequently or multiple browser tabs are open.

Quick Reference

Method	Path	Auth	Description
GET	/api/health	None (no mTLS)	Health check with version
GET	/api/system/stats	mTLS (admin or agent with system:read)	CPU, memory, disk, uptime
POST	/api/system/update	mTLS (admin only)	Trigger background update
POST	/api/agents/plugins/report	mTLS (admin or agent)	Report agent plugin capabilities

Response Shapes

Health:

{ "status": "ok", "version": "0.1.0" }

Stats:

{
  "cpu": { "usage": 12.5, "cores": 1 },
  "memory": { "total": 536870912, "used": 268435456, "free": 268435456 },
  "disk": { "total": 26843545600, "used": 5368709120, "free": 21474836480 },
  "uptime": 432000
}

Converting Bytes to Human-Readable

The API returns all size values in raw bytes. To convert:

Bytes	Formula	Result
536870912	/ 1024 / 1024	512 MB
26843545600	/ 1024 / 1024 / 1024	25 GB

curl Cheat Sheet

# Health check (no mTLS required)
curl -sk https://203.0.113.42:9292/api/health | jq

# System stats
curl -s --cert client.p12:password \
  https://203.0.113.42:9292/api/system/stats | jq

# Just CPU usage
curl -s --cert client.p12:password \
  https://203.0.113.42:9292/api/system/stats | jq '.cpu.usage'

# Memory in MB
curl -s --cert client.p12:password \
  https://203.0.113.42:9292/api/system/stats | jq '{
    total_mb: (.memory.total / 1048576 | round),
    used_mb: (.memory.used / 1048576 | round),
    free_mb: (.memory.free / 1048576 | round)
  }'