NATS Subjects
Reference for the NATS subject hierarchy used by Proxima Console.
System Subjects
| Subject | Pattern | Direction | Description |
|---|---|---|---|
| Config fetch | proxima.system.agent.config | Agent → Backend | Request-reply to fetch all remote configs for an agent at startup |
| Command channel | proxima.system.commands.{agent_id} | Backend → Agent | Publish-subscribe for runtime commands (config updates, future remote actions) |
| Agent renewal | proxima.system.agent.renew | Agent → Backend | Request-reply for JWT credential renewal |
| Config apply ack | proxima.system.config.apply.{agent_id} | Agent → Backend | Config apply result (success/failure per config type) |
The config fetch subject uses NATS request-reply. The agent sends {agent_id} and receives a map of all config types for that agent. See Agent — Config Fetch at Startup.
The command channel is a per-agent subject that the agent subscribes to after startup. The backend publishes to it when config changes via the API. Commands use a generic envelope format with type routing. See Agent — Command Channel.
The agent renewal subject uses NATS request-reply. The agent signs its current JWT with its nkey and sends it as proof of identity. The backend validates the signature, checks the agent is active in the agents table, and issues a new JWT with the name agent-{uuid}. Legacy JWTs with host-{uuid} prefix are rejected — agents must re-enroll. If NATS is unavailable, the agent falls back to HTTPS (POST /api/v1/agents/credentials/renew).
The config apply ack subject is published by the agent after it receives and applies a config push via the command channel. The payload includes config_type (which config was applied), version (the config version), status ("success" or "failure"), and error (error message, present only on failure). The backend worker subscribes to this subject to track config application outcomes per agent.
All subjects are governed by per-agent user JWT permissions. Each agent can only publish/subscribe to its own agent-scoped subjects. The JWT name uses the agent-{uuid} prefix. See NATS Security for the account model and permission details.
Telemetry Subjects (per-host)
| Subject | Pattern | Direction | Description |
|---|---|---|---|
| Inventory | proxima.{client}.{env}.{agent_id}.inventory | Agent → Backend | Full host inventory snapshot (includes labels). Only agent_type=host agents trigger host record creation. |
| Heartbeat | proxima.{client}.{env}.{agent_id}.heartbeat | Agent → Backend | Agent heartbeat with uptime and labels |
| Metrics | proxima.{client}.{env}.{agent_id}.metrics | Agent → Backend | System metrics batch |
| Processes | proxima.{client}.{env}.{agent_id}.processes | Agent → Backend | Full process list snapshot |
| Changes | proxima.{client}.{env}.{agent_id}.changes | Agent → Backend | File change events (baseline + delta scans) |
| Logs | proxima.{client}.{env}.{agent_id}.logs | Agent → Backend | Log entries from journald + file tailing |
| Kubernetes | proxima.{client}.{env}.{agent_id}.kubernetes | Agent/Seeder → Backend | Kubernetes cluster inventory (clusters, nodes, namespaces, workloads) |
Where {agent_id} is the UUID from the agents table, assigned at enrollment. It is not the host_id from the hosts table. The NATS JWT for each agent is named agent-{agent_id} and its publish/subscribe permissions are scoped to this same UUID.
Alert Subjects
These subjects support the alerting pipeline. See Alerting & Correlation for the full architecture.
| Subject | Pattern | Direction | Description |
|---|---|---|---|
| Alert ingest | proxima.alerts.ingest | Webhook → AlertWorker | Raw alert payload from webhook receiver, published after token validation |
| Alert correlate | proxima.alerts.correlate | AlertWorker → CorrelationWorker | Alert group ID for infrastructure enrichment (metrics, changes, related alerts, compliance) |
The alert ingest subject receives parsed Alertmanager payloads from the webhook handler. The AlertWorker resolves labels to Proxima entities, deduplicates alerts by fingerprint, and manages alert group lifecycle.
The alert correlate subject is published by the AlertWorker after successfully processing an alert. The CorrelationWorker queries VictoriaMetrics for metrics snapshots, PostgreSQL for recent changes and related alerts, and writes the enriched correlation context back to the alert group.
Terminal
| Subject | Pattern | Direction | Description |
|---|---|---|---|
| PTY output | proxima.{client}.{env}.{agent_id}.terminal.out.{session} | Agent → Backend | PTY output from a terminal session, streamed to browser |
| Terminal control | proxima.{client}.{env}.{agent_id}.terminal.ctrl.{session} | Agent → Backend | Terminal session control (start ack, reconnect ack) |
| Terminal commands | proxima.system.commands.{agent_id} | Backend → Agent | Terminal start/stop/detach/reconnect commands (shared with config sync and runbook dispatch) |
| Recording ready | proxima.{client}.{env}.{agent_id}.recording.ready | Agent → Backend | Notification that a session recording is ready for upload |
| Recording fetch | proxima.system.commands.{agent_id} | Backend → Agent | recording_fetch command to retrieve recording file from agent |
| Recording delete | proxima.system.commands.{agent_id} | Backend → Agent | recording_delete command to clean up local recording after upload |
| File transfer | proxima.system.file.{agent_id}.{transfer_id} | Bidirectional | Dedicated per-transfer subject for file upload/download data |
| File chunks | proxima.system.file.{agent_id}.{transfer_id}.chunks | Backend → Agent | Upload chunk data from browser to agent |
| File acks | proxima.system.file.{agent_id}.{transfer_id}.acks | Backend → Agent | Download chunk acknowledgments from browser |
The PTY output subject carries raw terminal output bytes from the agent's PTY process. Each session has a unique session ID in the subject, enabling multiplexed sessions on the same host. See Terminal Access for architecture details.
The terminal commands reuse the existing per-agent command channel (also used by config sync and runbook execution). Terminal commands use the terminal_start, terminal_stop, terminal_detach, terminal_reconnect, recording_fetch, and recording_delete command types within the generic envelope format.
The file transfer subjects use a dedicated proxima.system.file.{agent_id}.> namespace, separate from the agent's publish subjects. This keeps file transfer isolated from terminal I/O and follows the principle of least privilege — the agent's NATS JWT explicitly allows subscribe on this pattern. Each transfer gets a unique subject to prevent cross-transfer interference.
Port Forwarding (Tunnel)
| Purpose | Subject | Direction | Description |
|---|---|---|---|
| Tunnel commands | proxima.system.commands.{agent_id} | Backend → Agent | tunnel_start, tunnel_open, tunnel_close, tunnel_stop commands |
| Tunnel data in | proxima.{client}.{env}.{agent_id}.tunnel.in.{connection_id} | Backend → Agent | TCP data from CLI to remote endpoint |
| Tunnel data out | proxima.{client}.{env}.{agent_id}.tunnel.out.{connection_id} | Agent → Backend | TCP data from remote endpoint to CLI |
| Tunnel close | proxima.{client}.{env}.{agent_id}.tunnel.close.{connection_id} | Agent → Backend | TCP connection EOF notification |
| PTY exit | proxima.{client}.{env}.{agent_id}.terminal.exit.{session_id} | Agent → Backend | PTY process exited — triggers session cleanup |
Tunnel subjects follow the same per-agent scoping as terminal subjects. The tunnel.in.> pattern is explicitly allowed in the agent's NATS JWT subscribe permissions.
JetStream Streams
| Stream | Subjects | Max Age | Purpose |
|---|---|---|---|
| EVENTS | proxima.*.*.*.inventory, proxima.*.*.*.changes, proxima.*.*.*.heartbeat, proxima.*.*.*.kubernetes | 24 hours | Inventory snapshots, change events, heartbeats, Kubernetes inventory. The fourth wildcard matches {agent_id}. |
| TELEMETRY | proxima.*.*.*.metrics, proxima.*.*.*.processes, proxima.*.*.*.logs | 1 hour | High-volume metrics, process snapshots, and log data. The fourth wildcard matches {agent_id}. |
| ALERTS | proxima.alerts.> | 72 hours | Alert ingestion and correlation pipeline |
System subjects (proxima.system.*) are not on JetStream streams. They use core NATS request-reply or plain publish-subscribe.
Consumer Groups
Consumer groups ensure each message is processed exactly once across multiple backend instances. This allows horizontal scaling of the backend without duplicate processing.
| Consumer | Stream | Purpose |
|---|---|---|
backend-events-worker | EVENTS | Processes inventory, heartbeat, and change messages |
backend-metrics-worker | TELEMETRY | Processes metrics, process snapshots, and log entries via TelemetryWorker → MetricsWorker / ProcessesWorker / LogsWorker |
alert-worker | ALERTS | Label resolution, deduplication, alert grouping |
correlation-worker | ALERTS | Infrastructure enrichment (metrics snapshot, changes, related alerts, compliance) |