nats-fleet-agent
Command your servers through an outbound-dialing NATS control plane — no inbound firewall ports. Exec, file transfer, and a 7-day JetStream audit trail.
$ skillbank install nats-fleet-agent@1.0.0 # pins exactly 1.0.0 · README + changelog included
Overview
SSH is great until it isn't — flaky routes, NATed boxes, or a compliance team that wants every privileged command logged in one place. NATS Fleet Agent flips the connection around: a small Python agent on each server dials outbound to your NATS server over TLS. No inbound ports on the servers, no bastion hosts. You issue exec, upload, and download from the operator CLI, and every command *and* result is persisted for 7 days in a JetStream stream — the audit trail builds itself.
Per-agent credentials mean a compromised box can only talk about itself; it cannot command its neighbors.
Installation
1. The NATS server (your jump box, or one of the fleet machines) — as root:
./install-server.sh
This installs nats-server, enables TLS + JetStream, generates a CA and server cert, creates three passwords (operator + two agent users), and writes /etc/nats/nats-server.conf. Save the printed passwords — shown once. Copy /etc/nats/certs/ca.pem to each agent machine.
2. The agent on each server — as root, from this skill's directory:
./install-agent.sh <agent-id> tls://<nats-host>:4222 <agent-user> '<password>' ./ca.pem
The agent connects outbound, ensures the stream and object-store bucket exist, and serves vps.<agent-id>.exec / .upload / .download. Check journalctl -u nats-fleet-agent for the serving on vps.<agent-id>.> line.
3. The operator CLI — anywhere with Python 3.9+:
pip install -r requirements.txt # nats-py
Configuration
| Variable (agent) | Description |
|---|---|
VPS_AGENT_NATS_URL | tls://<nats-host>:4222 |
VPS_AGENT_NATS_USER | Per-agent user, e.g. web1-agent |
VPS_AGENT_NATS_PASSWORD | Agent password (secret, chmod 600 env file) |
VPS_AGENT_ID | Agent id, e.g. web1 (defaults to hostname) |
VPS_AGENT_CA_FILE | CA pem for self-signed server certs |
| Variable (operator CLI) | Description |
|---|---|
NCTL_NATS_URL | tls://<nats-host>:4222 |
NCTL_NATS_USER | operator |
NCTL_NATS_PASSWORD | Operator password — paste per session, never store |
NCTL_CA_FILE | CA pem |
Passwords are never logged or written by the tools (the install script's one-time print is the only exception — that's your cue to save them).
Inputs
| Command | Returns |
|---|---|
natsctl.py exec <agent> [--timeout N] <cmd...> | exit code, stdout, stderr (truncated at 1MB). |
natsctl.py upload <agent> <local> <remote> [mode] | Remote path + byte count. |
natsctl.py download <agent> <remote> <local> | Local path + byte count. |
natsctl.py ping <agent> | Round-trip latency. |
natsctl.py audit [n] | Last n entries of the command audit stream. |
File payloads travel through the JetStream Object Store (vps-files bucket) with automatic chunking, so the 1MB core-NATS message limit never matters; files up to 500MB are supported.
Worked example
$ export NCTL_NATS_URL=tls://nats.example.com:4222 NCTL_NATS_USER=operator $ export NCTL_NATS_PASSWORD='...' NCTL_CA_FILE=./ca.pem $ ./natsctl.py ping web1 pong from web1 in 41ms $ ./natsctl.py exec web1 --timeout 30 systemctl is-active nginx active $ ./natsctl.py upload web1 ./app.tar.gz /opt/app/app.tar.gz 644 uploaded 18432000 bytes -> /opt/app/app.tar.gz $ ./natsctl.py audit 3 2026-09-26T12:01:11Z operator web1 exec "systemctl is-active nginx" exit=0 2026-09-26T12:00:02Z operator web1 upload ./app.tar.gz -> /opt/app/app.tar.gz 2026-09-26T11:58:40Z operator db1 ping 38ms
Safety notes
This is remote code execution as root (the agent runs as a systemd service). Treat the operator password like a root password: paste per session, never commit it, rotate it if exposed. The 7-day audit stream is your accountability — review it. Agent users are scoped to their own subjects, but the operator credential is full fleet access by design.
Version history
- v1.0.02026-09-26
- Initial public release (generalized from a production-tested internal bundle).
- Agent dials outbound to NATS over TLS — zero inbound ports on managed servers.
- Operator CLI:
exec,upload,download,ping,audit. - JetStream persistence: every command + result kept 7 days (
VPS_CMDSstream); file payloads via object store (vps-filesbucket, up to 500MB). - Per-agent NATS users scoped to their own subjects; server/agent install scripts included.
- Tested end-to-end: install-server → install-agent → exec/upload/download/audit round-trip green.