Installer & site agent

Used by the installers and live systems a server boots over PXE, and by the site agents. They are listed so you can see the whole surface of a TrixOS installation; integrations don’t call them. Installer callbacks are authenticated with the per-job X-Job-Token, boot files only work while a job is armed, and the agent endpoints with the agent’s own token.

16 endpoints

First-stage iPXE script

GET/pxe/boot.ipxe

Chains to /pxe/boot with the booting MAC address.

Example

curl "https://panel.example.com/pxe/boot.ipxe"

Per-job iPXE script

GET/pxe/boot

For a MAC with an armed job: the job’s boot script. Otherwise: boot from disk.

Example

curl "https://panel.example.com/pxe/boot"

Installer files of a job

GET/pxe/jobs/{jobId}/{token}/{file}

preseed.cfg, user-data, ks.cfg, autounattend.xml, firstboot.sh, partition.sh, live.sh, smart.sh and more, only while the job runs.

Path parameters

jobId string
token string
file string

Example

curl "https://panel.example.com/pxe/jobs/JOB_ID/JOB_TOKEN/preseed.cfg"

Cached boot files

GET/pxe/assets/{*}

Kernels, initrds and live images from the boot-file cache.

Path parameters

* string

Example

curl "https://panel.example.com/pxe/assets/debian-13/linux"

Custom ISO for sanboot

GET/pxe/isos/{file}

Supports HTTP range requests.

Path parameters

file string

Example

curl "https://panel.example.com/pxe/isos/preseed.cfg"

Installer progress

POST/api/internal/jobs/{id}/progress

Header X-Job-Token. Body: stage (booted, installing, done, failed), pct, message, after (poweroff, reboot, running).

Path parameters

id string

Example

curl -X POST "https://panel.example.com/api/internal/jobs/42/progress" \
  -H "X-Job-Token: $JOB_TOKEN"

Installer log lines

POST/api/internal/jobs/{id}/log

Header X-Job-Token.

Path parameters

id string

Example

curl -X POST "https://panel.example.com/api/internal/jobs/42/log" \
  -H "X-Job-Token: $JOB_TOKEN"

SMART report of one disk

POST/api/internal/jobs/{id}/smart

Header X-Job-Token. The smartctl -j -x output of one disk, or {"trixos_error": "…"}.

Path parameters

id string

Example

curl -X POST "https://panel.example.com/api/internal/jobs/42/smart" \
  -H "X-Job-Token: $JOB_TOKEN"

Rescue system task poll (job token)

GET/api/internal/jobs/{id}/tasks

Path parameters

id stringuuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example

curl "https://panel.example.com/api/internal/jobs/42/tasks" \
  -H "X-Job-Token: $JOB_TOKEN"

Hardware report

POST/api/internal/jobs/{id}/hardware

Header X-Job-Token. Sent by the hardware collect image.

Path parameters

id string

Example

curl -X POST "https://panel.example.com/api/internal/jobs/42/hardware" \
  -H "X-Job-Token: $JOB_TOKEN"

Agent PXE state

POST/api/internal/agent/pxe

Which armed MACs the agent serves, its boot-file URL or the problem that stops it.

Request body

appliedstring[]
max. 256 items, default []
httpBasestring | null
pattern ^http:\/\/\d{1,3}(\.\d{1,3}){3}:\d{2,5}$, default null
problemstring | null
max. 500 chars, default null
eventsobject[]
max. 200 items, default []
- atintegerrequired
  > 0
- kindstringrequired
  one of discover, offer, request, ack, nak, tftp, tftp_error
- macstringrequired
  pattern ^[0-9a-f]{2}(:[0-9a-f]{2}){5}$
- ipstring | null
  max. 45 chars
- vendorstring | null
  max. 100 chars
- userstring | null
  max. 100 chars
- ignoredboolean
- detailstring | null
  max. 300 chars

Example

curl -X POST "https://panel.example.com/api/internal/agent/pxe" \
  -H "Content-Type: application/json" \
  -d '{"applied":[],"httpBase":null,"problem":null}'

Agent installer script

GET/agent/install.sh

Example

curl "https://panel.example.com/agent/install.sh"

Agent program

GET/agent/trixos-agent.py

Example

curl "https://panel.example.com/agent/trixos-agent.py"

Agent firewall script

GET/agent/agent-firewall.sh

Example

curl "https://panel.example.com/agent/agent-firewall.sh"

Register a site agent

POST/api/internal/agent/register

Uses the one-time install token.

Request body

installTokenstringrequired
pattern ^\d+\.[0-9a-f]{40}$
hostnamestring
max. 253 chars, default ""
wgPublicKeystring
max. 64 chars, default ""

Example

curl -X POST "https://panel.example.com/api/internal/agent/register" \
  -H "Content-Type: application/json" \
  -d '{"installToken":"installToken"}'

Agent heartbeat

POST/api/internal/agent/heartbeat

Every 60 s: version, host name, uptime, WireGuard state and allow-list. The answer carries the forwarding targets and update instructions.

Request body

versionstringrequired
max. 32 chars
hostnamestring
max. 253 chars, default ""
uptimeSnumber
≥ 0, default 0
osstring
max. 200 chars, default ""
wgobject
default {}
- handshakeAgeSnumber | null
- endpointstring | null
  max. 100 chars
- publicKeystring | null
  max. 64 chars
allowedstring[]
max. 4096 items, default []
metricsobject
- cpuPctnumber | nullrequired
  ≥ 0, ≤ 100
- cpusintegerrequired
  ≥ 1, ≤ 4096
- loadnumber[]required
  min. 3 items, max. 3 items
- memTotalnumberrequired
  ≥ 0
- memAvailablenumberrequired
  ≥ 0
- diskPathstring
  max. 200 chars, default "/"
- diskTotalnumberrequired
  ≥ 0
- diskUsednumberrequired
  ≥ 0
- diskAvailnumberrequired
  ≥ 0

Example

curl -X POST "https://panel.example.com/api/internal/agent/heartbeat" \
  -H "Content-Type: application/json" \
  -d '{"version":"version"}'