API reference

Log in and obtain a session token

Rate limited per source IP (20 a minute, burst 20) — generous enough that a whole team behind one NAT address can sign in normally, tight enough to put a ceiling on scripted guessing. A refusal is a 429 with Retry-After.

• 200AuthenticatedLoginResponse
• 401Missing or invalid credentialsError
• 429Too many login attempts from this address; retry after the Retry-After header says

Invalidate the current session

• 200Logged out

Current user and role

• 200The authenticated user
  • user User
  • role object

Change the current user's password

Rotates the caller's password, clears the first-run must-change flag, and issues a fresh session token (the old bearer is invalidated).

• current_passwordrequired string · password
• new_passwordrequired string · password

• 200Password changed; returns a rotated sessionLoginResponse
• 400Invalid requestError
• 401Current password incorrect

List servers

• 200Servers
  • servers array of Server

Create (deploy) a server from a spec

• spec_idrequired string · uuid
• namerequired string
• variables object
• memory_mb integerMemory to reserve. Omit to take the spec's own figure — its recommended memory, falling back to the minimum. An explicit value must be at least the spec's min_memory_mb: below that floor the game does not boot.
• node_id string · uuidPin placement to one node. The scheduler still checks eligibility and reserves; an ineligible pin is a 409 naming the reason rather than a silent placement elsewhere.
• install_bepinex booleanHonored only when the spec is bepinex_compatible.
• pin_build booleanPin the server to the build this install pulls: no update pass runs before later starts. Default false — every operator-initiated start/restart re-runs the install script first so the game picks up depot updates.
• steam_guard_code stringOne-time 2FA code for specs whose install needs an authenticated Steam login. Used for this install only, never persisted.

• 201CreatedServer
• 400Invalid requestError

Get a server

• idpathrequired string · uuid

• 200ServerServer
• 404Resource not foundError

Delete a retired server permanently

Only a retired server can be deleted: retire a live one first (POST /servers/{id}/retire), which is what removes its containers and world. The node the server was retired from is told to delete what is left of it and its backup archives — but only where they are its own: the zero-config node-local layout keeps each server's archives in <backup_dir>/<server_id>/, and those are deleted. A configured backup directory, a network share, SFTP and SMB keep every server's archives side by side, where an archive cannot be attributed to one server; those are kept, and note names where. An Agent too old to delete archives keeps them too, and note says so. Then the record and its schedules are deleted.

A node that cannot be reached does not block the delete: the removal, delete_backups included, is recorded on the node as a pending removal (see Node.pending_removals) and the node reconciler finishes it when the node answers; removal_pending is then true. A delete whose removal cannot be recorded is refused. Requires server.delete.

• idpathrequired string · uuid

• 200Deleted (the node-side removal may still be pending)PermanentDeleteResult
• 404Resource not foundError
• 409code: server_not_retired — the server is not retired; retire it first. code: server_restoring or server_busy while a restore or a retire holds a live server, and server_busy while a revive holds a retired one or its retire is still letting go ("the retire is finishing — retry in a moment"). Nothing was sent to the node.Error
• 500The node the server was retired from could not be read, or the removal could not be recorded on it; nothing was deleted.Error

Retire a server — keep its id, config, schedules and backups; remove its containers and world

What the delete button does. Runs in the background and answers at once: 202 with the server in state retiring and a retire block (the state it came from, a phase moving stopping → backing_up → removing, and the final backup's outcome); poll GET /servers/{id} until the state is retired — or, for an abandoned retire, back to what it was. The retire stops the server, takes a final backup unless final_backup is false and waits for it to be ready (at most 30 minutes), then has the node remove the server's containers and data directory — never its archives — releases its memory and ports, deletes its DNS records and port forwards, and switches its schedules off (they are kept, flagged, and the first install that lands after the retire — the revive's, or a reinstall after a revive whose install failed — switches back on exactly those). The retired server is on no node: node_id is empty, retired_from_node_id names where its archives are, and retired_ports the ports it held.

While the node answers, nothing is removed unless the final backup that was asked for is READY. A final backup that fails, or is still being written after 30 minutes, abandons the retire: nothing is removed, the server goes back to the state it came from (offline if the retire had stopped it) and last_error and retire_note say why, starting "retire abandoned:". A backup that could not be tried (the stop or the backup did not reach the node) is tried again when the removal is due, if the node answers then; only a node unreachable at that moment gets its removal queued without a backup — as a pending removal holding the allocation (see Node.pending_removals) — and retire_note says so ("final backup skipped: node unreachable"). A stop the node answers with a refusal abandons the retire as well, and the reason says the way through: retire again with final_backup false, which does not depend on the stop's result: a refusal does not hold it up, and the removal force-removes the container. A retire whose removal cannot be recorded is abandoned too. While it runs, every writer answers 409 server_busy. Requires server.delete.

• idpathrequired string · uuid

• final_backup booleantake a backup after the stop and before the removal

• 202The retire started; the server is retiringServer
• 400Invalid requestError
• 404Resource not foundError
• 409Nothing was started. code: server_retired — already retired. code: server_busy — installing, or a start, restart, reinstall, retire or revive holds the server. code: server_restoring — a backup restore is running.Error

Revive a retired server — place it, install it, optionally restore a backup and start it

Places a retired server on a node again — node_id, else the node it was retired from, else (that node being gone) wherever the scheduler finds room — on the platform it ran on, with its old memory unless memory_mb says otherwise. Its old ports are asked for first and kept where they are free on that node; a port taken since falls back to the spec's default, then the lowest free one. Answers 202 with the server installing; the install pass then runs as a create's does (a failure lands install_failed). When it lands, the backup restore_backup_id is restored through the same job as POST /servers/{id}/backups/{backupId}/restore (restoring, then offline with restore_result), and — when start is true and the restore (if any) succeeded — the server is started as an operator start would start it; a start that is refused or fails lands offline with last_error. The schedules the retire switched off are switched back on once the install lands — by this install, or by a later reinstall when this one fails. Requires server.create.

• idpathrequired string · uuid

• node_id stringplace it on this node; default the node it was retired from
• memory_mb integerdefault its old memory; must clear the spec's minimum
• restore_backup_id stringa ready backup of this server on the node it lands on
• start booleanstart it once the install (and the restore) succeeded
• steam_guard_code stringone-time 2FA code for an authenticated Steam install

• 202Placed; the install is runningServer
• 400Invalid requestError
• 404No such server (or one this user may not reach), or code: node_not_found — the node_id asked for does not exist.Error
• 409Nothing was changed. code: server_not_retired — only a retired server can be revived. code: server_busy — a permanent delete or another revive holds it, or its retire is still letting go ("the retire is finishing — retry in a moment"). code: removal_pending — the retire's removal of the old containers and world is still owed to a node, and would delete the revived world when it landed; revive once it has, or dismiss it. code: backup_not_found / backup_not_ready — the backup to restore is not a ready archive on that node. code: spec_missing / platform_missing — the spec, or the platform the server ran on, is gone. code: server_busy — another revive holds it. No code — no node can host it (the scheduler's reason, per node).Error
• 503code: node_unreachable — the backup to restore could not be checked on the node.Error

Power action (start/stop/restart/kill)

Start and restart re-run the server's install script before launching, so the game picks up depot updates, unless one of these skips it: the server pins its build, the spec sets skip_update_on_start (per spec or per platform), the server's create or reinstall completed within the last 30 minutes (so the pass would only repeat it), or the spec needs an authenticated Steam login and the node has no stored credentials. GET /servers/{id}/settings reports which way the next start will go. That pass is asynchronous: the response is then 202 with state installing (the console streams the install log), and the server continues to running on its own. Where a failed pass lands depends on the phase: a stop (or agent connection) that fails before the install restores the previous state with last_error set and no reinstall gate, a failed install script lands in install_failed and refuses start until a reinstall, and a failed start over a good install lands in offline. Stop/kill, and a start that skips the pass, still answer 200 with the new state.

• idpathrequired string · uuid

• 200New lifecycle state
  • state ServerState
• 202Update pass started; the server is installing and will start when it finishes
  • state ServerState
  • updating boolean
• 409Start or restart refused: the server is installing, its install failed (reinstall first), it is retired (code: server_retired, for every action, stop and kill included — it is on no node), a retire or revive holds it (code: server_busy), a backup restore is running (code: server_restoring — stop and kill still reach the agent, and the state stays restoring until the restore ends), the game spec it was built from no longer exists (code: spec_missing; permanent, since a spec's id cannot be recreated), or a setting its spec marks required is empty (code: required_settings_missing, with the keys in missing_settings). Nothing was attempted and the server's state is unchanged. Stop and kill are never refused for any of these. The node's agent can also refuse a start or restart while an install pass for the server is running on it (code: install_running); retry once it ends.StartRefusal
• 500The server's spec could not be read (a store error, not a missing spec), so start and restart were refused rather than run unchecked and nothing was attempted — or the node reported a failure it did not classify (code: node_error), with its message in error.Error
• 503code: node_unreachable. Either the panel has no live connection to the hosting node's agent — then nothing was attempted and the server's state is unchanged — or the agent did not answer within the time allowed, and the action may still be completing on the node (a stop still inside its graceful-stop window, say): error says which.Error

Re-run the install script once, now

Both the retry for a failed install and the explicit "update now" for a server whose start does not update it (a pinned build, or a spec that opted out of update-on-start). Valid from the stopped states — install_failed, offline, crashed — and refused while the server is installing, starting, running, stopping or restoring (the last with code: server_restoring). Runs asynchronously: the server flips to installing and the install log streams over the console socket.

• idpathrequired string · uuid

• steam_guard_code stringOne-time 2FA code for specs whose install needs an authenticated Steam login.

• 202Install started
  • state ServerState
• 409The server is not in a stopped state

Read the retained output of the server's most recent install

The install runs on the Agent and is streamed to the Panel, which buffers it in memory: there is no container left to tail once the phase ends. The buffer is kept after the install finishes — success included, since an installer can exit 0 having produced a broken tree — until the server is retired or deleted. A new attempt (a reinstall, or the update pass before a start) does not discard the one it replaces: that attempt is answered as previous, exactly one back, so a reinstall retrying a failed pass keeps the output that says why it failed. The new attempt is opened before the request that starts it is answered, so a read made once the server shows installing already returns that attempt. It does NOT survive a Panel restart; retained is false when nothing is held, which is not the same as an install that printed nothing.

• idpathrequired string · uuid

• 200Buffered install output
  • server_idrequired string
  • donerequired booleanthe attempt reached a verdict
  • retainedrequired booleanthis Panel process still holds a buffer
  • started_ms integer · int64
  • finished_ms integer · int64
  • linesrequired array of InstallLogLine
  • previousrequired objectThe attempt the current one replaced (an InstallAttempt), or null when there is none — never absent. Only one back is kept; a previous attempt is over, so done is always true, and finished_ms is absent when it was superseded before it reached a verdict.

Get grouped game settings + current values

• idpathrequired string · uuid

• 200Settings (groups + values), and what the next start does about updatesServerSettings

Update game settings values

Send only the settings you are changing. Every key in values is stored on the server verbatim — the panel never compares a value with the spec's default — so a key sent back unchanged becomes the server's own value. A client that GETs the settings and PUTs the whole values map back therefore freezes every value listed in from_spec: it stops following the spec's default and is no longer reported as from the spec. The web UI sends only the fields the operator edited. Sending a blank for a required field that has a spec default hands it back to that default.

• idpathrequired string · uuid

• values object
• variables object
• pin_build booleanThe server's build pin. Omit to leave it unchanged — an ordinary settings save must not unpin a server.

• 200Applied. The body carries values and from_spec as the GET returns them (a required field stored blank still yields to the spec's default, and a save of another field keeps it blank on the server), plus variables, applied, restart_needed, hot_reload, variables_changed and pin_build.
• 400The body is invalid, or a value is outside what the spec allows (a read-only setting, a variable that is not editable) — or the settings were saved and the node refused a config file's path as one that can never work (code: bad_path).Error
• 404No such server — or the settings were saved and the node reported a config file's folder missing (code: not_found).Error
• 409The settings were saved, but the node refused the rendered config files: code is file_in_use, node_refused or already_exists, and error begins "settings saved but config apply failed:".Error
• 500The settings could not be saved — or they were saved and applying the config failed on the Panel (code: config_apply_failed, a render error) or on the node (code: node_error). When the save itself succeeded, error begins "settings saved but config apply failed:".Error
• 503The settings were saved, but applying them did not complete (code: node_unreachable): the node's agent could not be reached, or it did not answer within the time allowed — in which case the config may still have been written on the node.Error

List game specs

• 200Specs
  • specs array of Spec

Create a spec (accepts JSON or YAML body)

• 201CreatedSpec

Get a spec

• idpathrequired string · uuid

• 200SpecSpec

Update a spec (JSON or YAML)

• idpathrequired string · uuid

• 200UpdatedSpec

Delete a spec

• idpathrequired string · uuid

• 204Deleted
• 404Resource not foundError
• 409Refused while any server is built from the spec: a server keeps its spec's id for life, and could never start again without it.
  • error string
  • code stringspec_in_use
  • servers integerhow many servers use the spec

List nodes

• 200Nodes
  • nodes array of Node
  • panel_version stringthe Panel's own build — an agent_version that differs is version skew

Register a node

• 201RegisteredNode

Live host vitals for every node

Cpu, memory, disk, network and temperature for each node, as sampled by its Agent and cached by the Panel (refreshed every 5s). Intended to be polled for the node instrument bands.

A node appears only when the Panel holds a recent reading for it: nodes that are unreachable, or whose Agent predates the telemetry RPC, are absent from the map rather than present with zero values. Within a node, each metric group carries a *_known flag — false means the host could not supply that metric (a Windows host has no temperature source, for example) and the value must be rendered as "no data", never as 0.

• 200Telemetry keyed by node id
  • nodes object

Get a node

• idpathrequired string

• 200NodeNode

Rename a node, or update its schedulable capacity (total memory, game-port range)

• idpathrequired string

• name stringDisplay name; servers reference a node by UUID, so renaming never disturbs what is running. Must not be blank.
• total_memory_mb integerMust cover memory already reserved by servers on the node
• port_start integerSet together with port_end; existing allocations are preserved
• port_end integer

• 200Updated nodeNode
• 400Invalid capacity values

Deregister a node

• idpathrequired string

• 204Deleted

Push this Panel's embedded agent binary to the node (admin)

Streams the agent build embedded in this Panel (always the Panel's own version) to the node over the mTLS gRPC channel. The agent verifies the checksum, swaps its binary transactionally (keeping the previous build for automatic rollback), and restarts. Dev Panel builds embed no agent binaries and return 503. Containerized agents refuse the push — pull the new image instead.

• idpathrequired string

• 200Binary pushed; the agent is restarting into it
  • from_version string
  • to_version string
  • bytes integer
  • restarting boolean
• 409Agent already at the Panel's version
• 503Agent unreachable, or no embedded agent binary in this Panel build (reason verbatim)

Live Agent info (pings the node over mTLS, brings it online)

The Agent's live NodeInfo, including running_servers, managed_containers (with each container's state) and containers_reported, read the same way as on the Node schema.

• idpathrequired string

• 200Live node info
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Power action sent straight to one node's agent

A lower-level power path than POST /servers/{id}/power: it forwards the action to the named node's agent and does not run the update pass, re-push the spec or render config. Start and restart are refused on the same grounds as the server-scoped endpoint, with the same bodies.

• idpathrequired string
• serverIDpathrequired string · uuid

• 200The agent's reported state
  • state stringthe agent's enum name, e.g. SERVER_STATE_RUNNING
• 400Invalid requestError
• 404No such node (node not found). Or the server is not reachable through this node's path (code: not_found, "server not found on this node"): no such server, a server that lives on a different node, or one this user may not reach. Those three answer with the same body, so a caller probing other nodes' paths learns neither which servers exist nor where they live. Nothing was sent to any agent. A 404 can also be the agent's own not-found, passed through with code: not_found.Error
• 409Start or restart refused: the server is installing, its install failed, a backup restore is running (code: server_restoring), its spec no longer exists (code: spec_missing), or a required setting is empty (code: required_settings_missing, with the keys in missing_settings). Nothing was sent to the agent. Or the agent refused a start or restart because an install pass for the server is running on the node (code: install_running); retry once it ends.StartRefusal
• 500The server's spec could not be read, so start and restart were refused — or the node reported a failure it did not classify (code: node_error), with its message in error.Error
• 503The panel could not reach the node's agent, or the agent did not answer within the time allowed (code: node_unreachable). A timed-out stop or restart may still be completing on the node.Error

Retire an untracked container (data untouched)

Stops and removes the container a node runs for a server id the Panel has no server on that node for — an entry of managed_containers that no server row matches — and has the Agent forget its spec so its watchdog never adopts it again. The server's data directory and backups are left exactly where they are. Requires server.delete and node.manage.

• idpathrequired string
• serverIDpathrequired stringthe server id from the container's kraken.server_id label, as listed in managed_containers

• 204Retired; the container is gone and the node's managed_containers no longer lists it
• 400Malformed server id (code: invalid_server_id)CodedError
• 403Missing server.delete or node.manage (code: forbidden)CodedError
• 404Node not found (code: node_not_found)CodedError
• 409Refused, nothing sent to the node. code: server_tracked — the Panel tracks a server with this id on this node; delete the server instead. code: removal_pending — a removal is already owed for this id (it may delete the data), so a retire that promised the data stays would be undone by the next replay; let it finish, or dismiss it first.CodedError
• 500The node answered but could not remove the container, its reason verbatim — a container engine the Agent cannot reach included ("docker: cannot connect to the daemon: …") — code: node_error; or the Panel could not read its own records (code: internal).CodedError
• 503code: node_unreachable. The node's Agent could not be reached — nothing was sent — or it did not answer within the time allowed, in which case the removal may still be completing on the node.CodedError

Dismiss a pending removal without delivering it

Forgets a removal the node owes — for a node that is gone for good, or a container cleared by hand — and releases the memory and ports it was holding. Nothing is sent to the node: if the container is in fact still running, retire it or remove it on the host. Requires server.delete and node.manage.

• idpathrequired string
• serverIDpathrequired stringthe server_id of an entry in the node's pending_removals

• 204Dismissed; the record is gone and its allocation released
• 400Malformed server id (code: invalid_server_id)CodedError
• 403Missing server.delete or node.manage (code: forbidden)CodedError
• 404Node not found (code: node_not_found), or no removal is pending for this id (code: removal_not_found)CodedError
• 500The Panel could not read or update the node record (code: internal). Nothing is sent to the node, so no Agent status applies.CodedError

Get a node's backup/credential config (stored secrets are never echoed)

• idpathrequired string

• 200Node configNodeConfigView
• 404Resource not foundError

Update a node's backup/credential config and push it to the Agent

Omitted fields keep their stored value; "" clears one. Saving pushes the config to an online Agent, which verifies the configured remote — the apply_* fields report that outcome, and a failure there is not a save failure.

• idpathrequired string

• 200Saved config plus the Agent apply resultNodeConfigView +
  • applied booleanthe config reached the Agent
  • apply_ok booleanthe configured target(s) verified
  • apply_detail string
• 400Unknown backup_target, an unrecognized path token, or both replication mirrors enabled
• 404Resource not foundError

List files under a path

• idpathrequired string · uuid
• pathquery stringdirectory to list

• 200Directory listing
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Read a single file's contents

• idpathrequired string · uuid
• pathqueryrequired string

• 200File content (capped)
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Download a single file (raw bytes)

Streams the file. Authenticate either with the ordinary session bearer, or with a one-time token from /files/download-token — the token form is what lets a plain download link carry the authorization, so the browser streams to disk instead of buffering the payload in memory. When token is present the Authorization header is not consulted at all, and path must be exactly the path the token was minted for.

The response carries Content-Length when the Agent announced the file's size (an older Agent does not, and then there is none), so a truncated transfer is detectable rather than arriving as a complete download. Accept-Ranges: none goes out either way: a download token is single-use, so a ranged second request could only be refused. Rate limited per source IP (30 a minute, burst 10).

• idpathrequired string · uuid
• pathquery stringThe file to stream. Required on the session-authenticated form; on the token form it may be omitted, since the token already names the path — supplied, it must match that path exactly or the request is refused.
• tokenquery stringA one-time download token from POST /servers/{id}/files/download-token. Single-use, 60 seconds, bound to one server, one exact path set and the user who minted it. Present, it is the whole authority for the request and no Authorization header is read; absent, the route authenticates as it always has.

• 200Raw file stream
• 400No path was supplied on the session-authenticated form, or the path can never work — it escapes the server's data directory, or names a folder (code: bad_path)
• 401Unknown, expired, already-used or wrong-server/wrong-path download token — or the session that minted it is gone
• 404No such server, or one this user may not reach (existence is not revealed) — or no such file on the node (code: not_found); the body is a JSON error, never a file
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 429Too many token redemptions from this address; retry after the Retry-After header says
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Download a token's path set as a zip

The GET twin of the zip route, for a plain download link. It carries no body: the paths come from the one-time token, which is also the only thing that authorizes it. Required — without a token there is nothing to stream.

• idpathrequired string · uuid
• tokenqueryrequired stringA one-time download token from POST /servers/{id}/files/download-token. Required here: it is both the authorization and the only source of the paths.

• 200Zip stream
• 400No token was supplied
• 401Unknown, expired, already-used or wrong-server download token — or the session that minted it is gone
• 404No such server, or one this user may not reach (existence is not revealed) — or a path that does not exist on the node (code: not_found); the body is a JSON error, never a file
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 429Too many token redemptions from this address; retry after the Retry-After header says
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Download selected paths as a zip

• idpathrequired string · uuid

• paths array of string

• 200Zip stream
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Mint a one-time download token

Issues an opaque token that authorizes exactly one download of exactly one path set on this one server, for 60 seconds, on behalf of the calling user. It is redeemed on GET /files/raw or GET /files/download and deleted on first use; the user's permission is re-checked at redemption, so a revoked role takes effect immediately, and so is the minting session, so logging out or having that session revoked kills any token it minted. The token is held in the Panel's memory only, never persisted, and never a session credential. Requires server.files.read — the same permission the raw route carries.

• idpathrequired string · uuid

• path stringOne file, for a token redeemable on GET /files/raw.
• paths array of stringA path set, for a token redeemable on GET /files/download.

• 201Token minted
  • url stringThe tokenised URL to navigate to.
  • token string
  • kind stringrawzip
  • expires_at string · date-time
  • expires_in_seconds integer
• 400No path, both shapes at once, or a path that escapes the tree
• 404No such server, or one this user may not reach (existence is not revealed)

Create a directory

• idpathrequired string · uuid

• 201Created
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Move/rename a path

• idpathrequired string · uuid

• 200Moved
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Copy a path

• idpathrequired string · uuid

• 200Copied
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Write/overwrite a file

• idpathrequired string · uuid

• 201Written
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Upload files (multipart)

The request body is capped at 64 MiB plus a megabyte of multipart framing; anything larger is refused outright rather than spooled to the Panel's disk.

• idpathrequired string · uuid

• 201Uploaded
• 400The body is not a valid multipart form, names no files, or targets a path that can never work (code: bad_path)
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 413The upload is larger than the Panel accepts
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Delete paths

• idpathrequired string · uuid

• 200Deleted
• 400The path can never work: it escapes the server's data directory, or names the data root where a file or folder is required (code: bad_path).Error
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

List backups

Also answers for a retired server — keeping its archives listable is the point of retiring — from the node it was retired from. When that node no longer exists the answer is 404 not_found: its archives went with it.

• idpathrequired string · uuid

• 200Backups
  • backups array of Backup
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Create a backup

• idpathrequired string · uuid

• name string

• 202Archiving started; poll the list for the backup to reach readyBackup
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Restore a backup

Only valid while the server is stopped (state offline, crashed or install_failed). Runs asynchronously: the server enters restoring at once, and GET /servers/{id} carries a restore block (the archive, the state to return to, when it began, the phase and the compressed bytes read) until the restore ends. While it runs every writer of the server's tree answers 409 server_restoring — start, restart, reinstall, server delete, settings save, backup create and delete, and every file write, upload, move, copy, mkdir and delete (reads and downloads are not refused) — and scheduled restarts, backups, commands and replication are skipped with the reason in the schedule's last_error. When it ends the server goes back to the state it came from (restore.prev_state), and restore_result records the outcome; a failed restore's reason says whether the files were rolled back. last_error is never written by a restore.

• idpathrequired string · uuid
• backupIdpathrequired string

• 202Restore started; the server is restoringServer
• 409The server is not stopped, a restore is already running for it (code: restore_in_progress), a start, restart or reinstall is in flight and still holds the server (code: server_busy — its row may read offline until the agent answers), a retire holds it (code: server_busy, state retiring), or it is retired (code: server_retired). Nothing was started.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

Delete a backup

• idpathrequired string · uuid
• backupIdpathrequired string

• 204Deleted
• 404No such server, or one this user may not reach (existence is not revealed) — or the path or backup does not exist on the node (code: not_found).Error
• 409The node refused the operation, and code says why: file_in_use (another process holds the file — usually the server's own game, still running), node_refused (the node's filesystem denied it) or already_exists. error carries the node's own words. On an operation that writes the server's files, server_restoring means a backup restore holds them and server_busy that a retire, revive or delete holds the server; nothing was sent to the node. On a retired server every file and backup route but the backup list answers server_retired (revive it first).Error
• 500The node reported a failure it did not classify (code: node_error); error carries its message.Error
• 503The panel could not reach the node's agent, or it did not answer in time (code: node_unreachable).Error

List a server's scheduled tasks

• idpathrequired string · uuid

• 200Schedules
  • schedules array of ScheduledTask

Create a scheduled task

• idpathrequired string · uuid

• 201CreatedScheduledTask
• 400Invalid requestError

Update a scheduled task

• idpathrequired string · uuid
• scheduleIdpathrequired string · uuid

• 200UpdatedScheduledTask

Delete a scheduled task

• idpathrequired string · uuid
• scheduleIdpathrequired string · uuid

• 204Deleted

List users

• 200Users

Create a user

• 201Created

Update a user

• idpathrequired string · uuid

• 200Updated

Delete a user

• idpathrequired string · uuid

• 204Deleted

Reset a user's password

• idpathrequired string · uuid

• 200Reset

List roles

• 200Roles

List known permissions

• 200Permissions

Issue a one-time Agent bootstrap token (admin)

• node_name stringaudit-log label only (default "remote-agent") — the node's real name comes from the agent at registration
• ttl_seconds integertoken lifetime (default 900)

• 201Token issued
  • token string
  • node_name string
  • expires_at string · date-time
  • ca_fingerprint stringfull SHA-256 fingerprint of the Panel CA — embed in the agent's install command as --ca-fingerprint to pin the enrollment
• 503CA signing not configured

Poll a bootstrap token's lifecycle (pending → redeemed)

Lets the setup wizard show live enrollment progress. Once redeemed, the response includes the enrolling source IP and the hosts the agent baked into its certificate (its reachable addresses) so node registration can be prefilled.

• tokenqueryrequired string

• 200Token state
  • status stringpendingredeemedexpired
  • node_name string
  • ip string
  • hosts array of stringagent-advertised reachable addresses, IPs first
  • agent_port integeragent-reported gRPC port for the registration prefill
  • expires_at string · date-time
  • redeemed_at string · date-time

Enroll an Agent — exchange a bootstrap token + CSR for a signed cert

Authenticated solely by the one-time bootstrap token (the Agent has no session yet). Returns the signed Agent certificate and the CA cert. Re-enrolling with a fresh token rotates the certificate.

• tokenrequired string
• csrrequired stringPEM-encoded certificate signing request
• agent_port integergRPC port the agent will serve on (default 9090) — used to prefill node registration

• 200Signed certificate + CA (PEM)
  • certificate string
  • ca string
• 401Invalid/expired bootstrap token

First-run onboarding progress

The whole /setup/* surface answers only requests whose source IP falls inside KRAKEN_SETUP_ALLOWED_CIDRS (default: loopback + private ranges); external sources receive 403 regardless of credentials. setup_complete latches true permanently once onboarding finishes (computed complete once, or explicitly dismissed).

• 200Setup status
  • admin_must_change_password boolean
  • using_memory boolean
  • has_node_online boolean
  • has_spec boolean
  • has_server boolean
  • setup_complete boolean
• 403Source IP outside the setup allowlist

Mark first-run onboarding as finished (hides the Setup shortcut permanently)

• 200Dismissed
  • setup_complete boolean
• 403Source IP outside the setup allowlist

Current datastore target (never returns the password)

• 200Datastore config
  • using_memory boolean
  • env_locked booleanmanaged by KRAKEN_DATABASE_URL
  • host string
  • port integer
  • user string
  • dbname string
  • sslmode string

Connect Postgres — create DB if needed, migrate, persist, restart

• 200Saved; the Panel will restart onto Postgres
  • restarting boolean
• 400Invalid requestError
• 409Database is env-managed (KRAKEN_DATABASE_URL)
• 502Connection / create / migrate failed

Preflight a Postgres connection

• 200Reachable
  • ok boolean
  • db_exists boolean
  • can_create_db boolean
• 400Invalid requestError
• 502Connection failed

Issue a bootstrap token for the co-located Agent (loopback only)

Mints a one-time enrollment token for the local single-host Agent. Gated on a loopback source IP; not reachable off-host.

• 201Token issuedBootstrapToken
• 403Not called from the Panel host
• 503Agent enrollment not configured

List bundled starter game specs

• 200Catalog entries
  • catalog array of CatalogItem

Import a bundled catalog spec (one-click)

• idpathrequired string

• 201ImportedSpec
• 404Catalog item not found
• 409A spec with that slug is already imported

Panel-global settings status (never returns secrets)

• 200Settings statusSettingsView

Update Panel-global settings (Cloudflare token, UniFi gateway)

• cloudflare_api_token stringScoped Cloudflare API token; empty string clears it
• unifi_url stringUniFi controller base URL, e.g. https://192.168.1.1
• unifi_api_key stringUniFi OS API key; empty string clears it
• unifi_site stringUniFi site (default 'default')

• 200SavedSettingsView

Verify the stored Cloudflare token by listing its zones

• 200Reachable zones
  • zones array of string
• 400Cloudflare not configured
• 502Cloudflare API error

Verify the stored UniFi credentials (lists forwards + WAN IP)

• 200Reachable
  • forward_count integer
  • wan_ip string
• 400UniFi not configured
• 502UniFi API error

Current DNS assignment + target for a server

• idpathrequired string · uuid

• 200DNS state
  • cloudflare_configured boolean
  • unifi_configured boolean
  • target_host stringexternal/WAN host for DNS + connect
  • lan_host stringnode LAN IP (port-forward target)
  • ports object
  • dns ServerDNS
  • forwards object

Assign a DNS name (creates A/CNAME + optional SRV in Cloudflare)

• idpathrequired string · uuid

• namerequired stringFQDN, e.g. play.example.com
• service stringSRV service label (e.g. minecraft); omit to skip SRV
• port_name stringspec port to advertise; defaults to the primary port

• 200Records created
  • dns ServerDNS
• 400Invalid requestError
• 409Refused, nothing changed: server_retired — the server is retired (revive it first); server_busy — a retire, revive or delete holds it; server_restoring — a backup restore holds it.Error
• 502Cloudflare API error
• 503Cloudflare not configured

Remove a server's DNS records

• idpathrequired string · uuid

• 200Removed

Open (create/enable) or close (disable) a UniFi port forward for a server port

• idpathrequired string · uuid
• portNamepathrequired string

• openrequired boolean

• 200Forward updated
• 400Invalid requestError
• 409Refused, nothing changed: server_retired — the server is retired (revive it first); server_busy — a retire, revive or delete holds it; server_restoring — a backup restore holds it.Error
• 502UniFi API error
• 503UniFi not configured

List recent audit entries (newest first)

• 200Audit entries
  • entries array of AuditEntry
  • retention_days integerhow many days of audit log the Panel keeps (KRAKEN_AUDIT_RETENTION_DAYS); 0 means entries are never pruned

Panel build version

The Panel's own build. Shown as the version stamp in the UI and compared against each node's agent_version to surface fleet version skew. Authenticated, so an unauthenticated caller can't fingerprint the build.

• 200Build metadata
  • version string
  • commit string
  • date string