Aegis documentation

#bird — the WebSocket transport

Bird is the platform's WebSocket transport: a small Rust daemon (aegis-r-bird) that forwards whatever the platform publishes to browser sockets. Producers write to a unix socket; Bird fans the messages out on two channels and knows nothing about Aegis, which keeps it reusable for any live feed.

bash
aegis bird

There is no aegis bird command in this build. Unlike pulse, collector or geoip, the module ships no CLI of its own: it owns the configuration, the keeper definition and the publish helper, and it is operated through the keeper and the panel. Running the command above is an argparse error (exit 2). The rest of this page documents the commands that do affect Bird, the protocol producers use, and the settings that change its behaviour.

#What Bird carries

text
producer ──(unix socket)──> aegis-r-bird ──(WebSocket)──> browser

A producer writes one line to /aegis/run/bird.sock:

text
<channel>\t<topic>\t<json>\n
ChannelURLWho may connect
public/ws/publicanyone
private/ws/private?token=…holders of bird.private_token

A topic is a routing label, not a permission: a socket receives only the topics it subscribed to, and the channel decides whether a token is required.

TopicProducerContent
corepulsehost facts, services, jobs, problems
networkpulseinterfaces, counters, peers
nginxpulsenew requests and stub-status counters
mailpulsedeliveries, queue depth, events
connectionspulseestablished sockets grouped by address
taskertaskerone log line, or a status change of one task
aithe AI daemondeltas, tool calls and the final status of a turn

Delivery is best effort on purpose. A live view that misses one message is corrected by the next snapshot, and a stopped Bird must never block the process that wanted to publish.

#Commands that operate Bird

#aegis status

The platform report: keeper, panel, boot hook, every supervised service and the scheduled jobs. Bird appears in the service table as aegis-r-bird; its state and uptime answer "is the transport up?" without touching Bird itself.

bash
aegis status
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis statusaegis status | grep -E 'bird|keeper'
text
Aegis status  keeper     running (pid 679986), up 3h 12m  panel      running (pid 680120), port 9981, up 3h 12m  boot hook  enabled (/etc/init.d/aegis-keeper)  services   9 running  service              state    pid     uptime  ---------------------------------------------  aegis-r-bird         running  679990  3h 12m  aegis-pulse          running  679991  3h 12m  aegis-tasker         running  679992  3h 12m  aegis-ai             running  679993  3h 12m  aegis-collector-net  running  680001  3h 12m  scheduled jobs    geoip-refresh  every 12h     last 2026-11-17 04:10:02  5 datasets refreshed    ssl-renew      every 6h      last 2026-11-17 03:00:11  1 certificate renewed

The command exits 1 only when the keeper itself is stopped.

#aegis keeper services

List what the keeper would supervise, with the live state and the pid file of each service. This is the fastest way to see whether Bird is registered at all: with bird.enabled = false it does not appear in the list.

bash
aegis keeper services
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis keeper servicesaegis keeper services | grep bird
text
service              state                 pid file───────────────────  ────────────────────  ──────────────────────────aegis-ai             running (pid 679993)  /aegis/run/ai.pidaegis-r-bird         running (pid 679990)  /aegis/run/bird.pidaegis-tasker         running (pid 679992)  /aegis/run/tasker.pid

A stopped service reads stopped; the pid file is printed even then, because that is where the keeper expects to find a live pid.

#aegis check

Run the platform health checks. The bird row answers four things in one line: the binary exists, the /health endpoint answers, the publisher socket exists and how many clients and messages Bird has seen. The hint column names the command that fixes the row.

bash
aegis check
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis checkaegis --json check
text
check      status  detail                                        hint─────────  ──────  ────────────────────────────────────────────  ─────────────bird       ok      port 9982 · 3 private · 148221 published      -pulse      ok      6 monitors · waiting: web, mail, network, connections, nginxnginx      ok      binary present

The three failure shapes are distinct:

text
bird       fail    binary missing                                aegis buildbird       fail    health: <urlopen error [Errno 111] Connection refused>  aegis restartbird       warn    publisher socket missing                      aegis restart

fail sets a non-zero exit code; warn does not.

#aegis restart

Disruptive. This stops every supervised service, starts them again in registry order and restarts the panel. Every open WebSocket is closed and every live view reconnects; work in flight on the tasker or the AI queue is interrupted.

Restart the keeper, every service it supervises (Bird included) and the panel. This is the command the health report points at when Bird is unhealthy, because the keeper has no per-service restart verb.

bash
aegis restart
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis restartaegis restart && aegis check
text
✔ web-admin: stopped (pid 680120)✔ keeper: stopped (pid 679986)✔ aegis-tasker: stopped (pid 679992)✔ aegis-r-bird: stopped (pid 679990)✔ aegis-pulse: stopped (pid 679991)✔ aegis-collector-net: stopped (pid 680001)✔ aegis-ai: stopped (pid 679993)✔ aegis-ai: started (pid 681207)✔ aegis-collector-net: started (pid 681204)✔ aegis-pulse: started (pid 681205)✔ aegis-r-bird: started (pid 681206)✔ aegis-tasker: started (pid 681208)✔ keeper: started (pid 681203)✔ web-admin: started (pid 681209) on 0.0.0.0:9981

A line that contains failed is printed as an error and makes the command exit 1.

#aegis keeper logs show bird

Print the rotation policy of every log whose path contains bird, plus the generations already on disk. Bird's own log is /aegis/logs/bird.log, classified as a service log: 8 MiB per file, four generations, compressed after rotation.

bash
aegis keeper logs show <part-of-path>
ArgumentDefaultMeaning
namerequiredpart of the log path, for example bird
bash
aegis keeper logs show birdaegis keeper logs show /aegis/logs/bird.log
text
log             /aegis/logs/bird.logclass           servicesize            3.4Mrotate at       8.0Mkeep            4compress        yesdelaycompress   yesgeneration      size──────────────  ──────bird.log.1.gz   812Kbird.log.2.gz   790K

A path that matches nothing exits 1:

text
✖ no log matches birdhouse

#The health endpoint

Bird serves a small JSON document on its listening port. The aegis check row is built from it, and it is the only way to read Bird's counters directly — the daemon exposes no other statistics API.

bash
curl -s http://127.0.0.1:9982/health

The port is bird.port (9982 by default). The document is unauthenticated, so keep the port behind the firewall; the WebSocket sockets, not this endpoint, are what browsers need.

bash
curl -s http://127.0.0.1:9982/healthcurl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9982/health
text
{"clients":{"public":12,"private":3},"published":148221}
text
200

published counts messages accepted from producers since the daemon started; clients is the number of connected sockets per channel. A connection refused means Bird is not running, or is listening on another port.

#The panel

Management → Bird is the graphical equivalent of the commands above. The page shows the settings that matter (enabled, listen, port, max_clients, queue, whether a token is set), the process state, the number of connected clients (counted from the kernel with ss, because Bird has no statistics API), the log tail and a connection series for the last 24, 48 or 72 hours. Its start, stop and restart actions are the per-service control the CLI does not expose.

The browser never hardcodes the connection details: after authentication it asks /api/live for the URL, path, channel, token and ping interval. A page served over TLS reaches Bird through nginx's same-origin /ws proxy, because a browser refuses a ws:// socket from an https:// page.

#Publishing a message

Anything on the host can publish: pulse, the tasker and the AI daemon use the same helper. It is app.modules.bird.publish.send.

python
from app.modules.bird import publishpublish.send(config, "private", "core", {"at": 1700000000, "services": 9})

send returns False when nobody is listening. It never raises, so a producer can publish without guarding its main loop:

python
if not publish.send(config, "tasker", "tasker", {"line": "deploy finished"}):    log.warning("bird is not listening")

The wire format is one line per message, fields separated by a tab:

text
private	core	{"at":1700000000,"services":9}

#Frames

Every server frame is binary. The first byte is the codec:

ByteBody
0x00the JSON document, uncompressed
0x01a 32-bit little-endian original size, then a zlib stream

Browsers expand the compressed form with DecompressionStream("deflate") — no library and no negotiation. bird.level sets the zlib level. A subscriber whose queue fills is dropped instead of being allowed to grow without bound.

#Configuration

All keys live under [bird] in config/aegis.toml.

toml
[bird]enabled = truelisten = "0.0.0.0"port = 9982private_token = "…"max_clients = 256queue = 64ping_interval = 20max_frame = 1048576level = 6
KeyDefaultMeaning
bird.enabledtrueregister the keeper service; false removes it
bird.listen0.0.0.0address the WebSocket listener binds
bird.port9982TCP port for sockets and /health
bird.private_token""token required by the private channel
bird.max_clients256concurrent sockets before new ones are refused
bird.queue64buffered messages per subscriber before it is dropped
bird.ping_interval20keepalive ping, seconds; 0 disables it
bird.max_frame1048576largest frame Bird accepts, bytes
bird.level6zlib compression level

Changing private_token invalidates open private sockets; the next page load receives the new value from /api/live.

The keeper definition is built by the module, not configured by path:

text
binary      /aegis/bin/aegis-r-birdcommand     aegis-r-bird --config /aegis/config/aegis.tomlpid file    /aegis/run/bird.pidlog file    /aegis/logs/bird.logsocket      /aegis/run/bird.sock

The prefix is the configured aegis.root; /aegis is this platform's root.

Bird does not write its own pid file (writes_pid=False); the keeper records the pid of the process it started.

#The publisher socket

/aegis/run/bird.sock is a unix socket, not a regular file, so test -f reports it missing even when it is healthy. Use test -S when checking by hand:

bash
test -S /aegis/run/bird.sock && echo listening

A missing socket while Bird is running means the daemon was started with a different run_dir, or never created the socket; a present socket with no listener is what the health check reports as publisher socket missing.

#Troubleshooting

bash
aegis statusaegis checkaegis keeper logs show bird
SymptomCheckUsual fix
binary missingls /aegis/bin/aegis-r-birdaegis build
health: connection refusedaegis keeper servicesaegis restart
publisher socket missingtest -S /aegis/run/bird.sockaegis restart
a page that renders once and never updatesaegis pulse statusthe producer, not Bird
unauthorized in the browsertoken changedreload the page
every client dropped at oncebird.max_clients / bird.queueraise the limit, lower the rate

Pulse publishes core; if aegis pulse status shows errors, the live view is empty even though Bird is healthy. Bird never invents a message.