Admin Commands

Nimbus exposes a line-based JSON admin socket at 127.0.0.1:42499 by default. The nimctl CLI is the standard way to talk it.

nimctl quick reference

# Health check
nimctl ping

# List connected players
nimctl list

# Show session detail for one player
nimctl status --player PlayerName

# Transfer a player to another backend
nimctl swap --player PlayerName --server factions
nimctl swap --player PlayerName --server factions --seamless

# Drain a backend (stop new players going there)
nimctl drain hub

# Return a drained backend to rotation
nimctl undrain hub

# List sticky reconnect routes
nimctl sticky

# List backends from registry snapshot
nimctl servers

# List loaded plugins
nimctl plugins

# Hot-reload config and plugins without restarting
nimctl reload

# Show all commands and descriptions
nimctl help

If the admin socket has a secret configured, pass it:

nimctl --secret "your-secret" ping

---

Command reference

Command	Aliases	Description
ping		Returns {ok: true, version: "..."}. Use for health checks and monitoring.
help	?	Lists all commands filtered by your granted permissions, with summaries and JSON usage examples.
list	ls, players	Lists every active session: session ID, player name, remote IP, current backend, phase, and byte counters.
status	inspect	Full detail for one session. Identify by player (name or UID) or id (session number).
kick	drop	Force-close a session immediately. Identify by player or id.
swap	send, transfer	Transfer a session to another backend. Required args: player (or id) and server. Optional: mode (redirect/seamless), reason.
drain		Remove a backend from the routing pool. Existing sessions continue; no new players go there. Required arg: server.
undrain	resume	Return a drained backend to rotation. Required arg: server.
servers	serverlist	Dumps the current registry snapshot: all backends with player counts, TPS, and maintenance status. Requires registry mode embedded or remote.
plugins	plugin	Lists loaded plugins: ID, name, version, API version, source file.
sticky	stickies	Lists all staged sticky reconnect routes (UID → target backend, remaining TTL).
route	routes	Shows the backend router pool: endpoint, drain flag, stale/maintenance status, and backend metadata from the registry.
reload		Hot-reloads nimbus.proxy.toml and all plugins. Returns the count of servers and plugins loaded after reload. Structural settings (bind, admin, registry, metrics) are not changed - restart for those.

---

Permissions

Each command has a permission node: nimbus.command.<name> (e.g. nimbus.command.swap).

The admin.granted_permissions list in the proxy config determines what an authenticated admin session can run. The default ["*"] grants everything. You can restrict to specific commands:

[admin]
granted_permissions = ["nimbus.command.list", "nimbus.command.status", "nimbus.command.swap"]

help always shows only commands the caller has permission for.

---

Socket protocol

The socket is raw TCP. Each message is one line of JSON followed by a newline. The response is one line of JSON.

If admin.secret is set, the first line must be the secret (plain text), not a command:

your-secret-here
{"cmd":"ping"}

Without a secret, send commands directly:

{"cmd":"ping"}

This makes it scriptable from any language:

import socket, json

s = socket.create_connection(("127.0.0.1", 42499))
s.sendall(b'{"cmd":"list"}\n')
data = b""
while b"\n" not in data:
    data += s.recv(4096)
response = json.loads(data)
s.close()

Or with netcat:

echo '{"cmd":"ping"}' | nc 127.0.0.1 42499

---

Example responses

ping:

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

list:

{
  "ok": true,
  "sessions": [
    {
      "id": 1,
      "name": "PlayerName",
      "uid": "abc123",
      "remote": "1.2.3.4",
      "server": "hub",
      "phase": "Ready",
      "c2s_bytes": 12345,
      "s2c_bytes": 98765
    }
  ]
}

swap:

{"ok": true, "mode": "redirect"}

reload:

{"ok": true, "message": "3 server(s), 2 plugin(s)"}