nats-fleet-agent

v1.0.0 MIT devops updated 2026-09-26

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_URLtls://<nats-host>:4222
VPS_AGENT_NATS_USERPer-agent user, e.g. web1-agent
VPS_AGENT_NATS_PASSWORDAgent password (secret, chmod 600 env file)
VPS_AGENT_IDAgent id, e.g. web1 (defaults to hostname)
VPS_AGENT_CA_FILECA pem for self-signed server certs
Variable (operator CLI)Description
NCTL_NATS_URLtls://<nats-host>:4222
NCTL_NATS_USERoperator
NCTL_NATS_PASSWORDOperator password — paste per session, never store
NCTL_CA_FILECA 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

CommandReturns
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

  1. 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_CMDS stream); file payloads via object store (vps-files bucket, 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.

← back to catalog