#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.
aegis birdThere 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
producer ──(unix socket)──> aegis-r-bird ──(WebSocket)──> browserA producer writes one line to /aegis/run/bird.sock:
<channel>\t<topic>\t<json>\n| Channel | URL | Who may connect |
|---|---|---|
public | /ws/public | anyone |
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.
| Topic | Producer | Content |
|---|---|---|
core | pulse | host facts, services, jobs, problems |
network | pulse | interfaces, counters, peers |
nginx | pulse | new requests and stub-status counters |
mail | pulse | deliveries, queue depth, events |
connections | pulse | established sockets grouped by address |
tasker | tasker | one log line, or a status change of one task |
ai | the AI daemon | deltas, 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.
aegis status| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis statusaegis status | grep -E 'bird|keeper'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 renewedThe 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.
aegis keeper services| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis keeper servicesaegis keeper services | grep birdservice 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.pidA 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.
aegis check| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis checkaegis --json checkcheck status detail hint───────── ────── ──────────────────────────────────────────── ─────────────bird ok port 9982 · 3 private · 148221 published -pulse ok 6 monitors · waiting: web, mail, network, connections, nginxnginx ok binary presentThe three failure shapes are distinct:
bird fail binary missing aegis buildbird fail health: <urlopen error [Errno 111] Connection refused> aegis restartbird warn publisher socket missing aegis restartfail 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.
aegis restart| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis restartaegis restart && aegis check✔ 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:9981A 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.
aegis keeper logs show <part-of-path>| Argument | Default | Meaning |
|---|---|---|
name | required | part of the log path, for example bird |
aegis keeper logs show birdaegis keeper logs show /aegis/logs/bird.loglog /aegis/logs/bird.logclass servicesize 3.4Mrotate at 8.0Mkeep 4compress yesdelaycompress yesgeneration size────────────── ──────bird.log.1.gz 812Kbird.log.2.gz 790KA path that matches nothing exits 1:
✖ 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.
curl -s http://127.0.0.1:9982/healthThe 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.
curl -s http://127.0.0.1:9982/healthcurl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9982/health{"clients":{"public":12,"private":3},"published":148221}200published 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.
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:
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:
private core {"at":1700000000,"services":9}#Frames
Every server frame is binary. The first byte is the codec:
| Byte | Body |
|---|---|
0x00 | the JSON document, uncompressed |
0x01 | a 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.
[bird]enabled = truelisten = "0.0.0.0"port = 9982private_token = "…"max_clients = 256queue = 64ping_interval = 20max_frame = 1048576level = 6| Key | Default | Meaning |
|---|---|---|
bird.enabled | true | register the keeper service; false removes it |
bird.listen | 0.0.0.0 | address the WebSocket listener binds |
bird.port | 9982 | TCP port for sockets and /health |
bird.private_token | "" | token required by the private channel |
bird.max_clients | 256 | concurrent sockets before new ones are refused |
bird.queue | 64 | buffered messages per subscriber before it is dropped |
bird.ping_interval | 20 | keepalive ping, seconds; 0 disables it |
bird.max_frame | 1048576 | largest frame Bird accepts, bytes |
bird.level | 6 | zlib 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:
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.sockThe 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:
test -S /aegis/run/bird.sock && echo listeningA 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
aegis statusaegis checkaegis keeper logs show bird| Symptom | Check | Usual fix |
|---|---|---|
binary missing | ls /aegis/bin/aegis-r-bird | aegis build |
health: connection refused | aegis keeper services | aegis restart |
publisher socket missing | test -S /aegis/run/bird.sock | aegis restart |
| a page that renders once and never updates | aegis pulse status | the producer, not Bird |
unauthorized in the browser | token changed | reload the page |
| every client dropped at once | bird.max_clients / bird.queue | raise 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.