About the Agent

A small Go binary that runs on your server and lets n8nmanager deploy and manage n8n on your behalf.

Overview

When you connect a server, we install the n8nmanager agent — a single statically-linked Go binary that listens for jobs from the dashboard and runs Ansible playbooks to install, upgrade, restart, back up, and monitor n8n on your machine.

The agent is designed to be transparent and inspectable. Everything it does happens locally on your server using standard tools you can audit (Ansible, Docker, systemd). Nothing leaves your server except outbound HTTPS calls to the dashboard API.

Current agent version is 2.0.0. Older servers may still be running the legacy 1.x Bash agent — they will auto-migrate to the Go agent on the next Update Agent action.

What runs on your server

  • /usr/local/bin/n8n-agent — the agent binary itself (statically-linked Go, ~10 MB).
  • /etc/n8n-agent/config.json — the API URL and your unique agent token (file mode 600, root-only).
  • /etc/systemd/system/n8n-agent.service — the systemd unit that keeps the agent running.
  • /opt/n8n-agent/playbooks/ — Ansible playbooks (install, upgrade, restart, backup, SSL, health check, uninstall).
  • /opt/n8n-agent/venv/ — isolated Python virtualenv that contains Ansible. Does not touch your system Python.
  • /opt/n8n-agent/src/ — the Go source we built the binary from. Kept on disk so you can read or rebuild it.
  • /opt/n8n-agent/logs/ — per-job log files plus the agent's own log.

How it communicates

The agent only makes outbound HTTPS calls. There are no inbound ports opened on your server.

  • POST /api/agent/register — on startup, registers hostname, OS, and agent version.
  • POST /api/agent/heartbeat — every 30 seconds; ships system metrics (CPU, memory, disk, Docker containers) and n8n metrics (workflows, executions, webhooks).
  • GET /api/agent/jobs — every 30 seconds; pulls any pending jobs you queued from the dashboard.
  • PATCH /api/agent/jobs/:id — reports job progress, logs, and final status.

Every request is authenticated with a per-server bearer token stored in /etc/n8n-agent/config.json. The token is generated when you click Generate Agent Token in the dashboard and can be rotated at any time.

Permissions and security

The agent runs as root via systemd because it manages Docker containers, writes to /etc, issues TLS certificates, and configures system services — all of which require root privileges.

  • The agent token is the only secret on disk and is stored with mode 600 (root-only read/write).
  • The agent never accepts inbound connections. It is poll-based, so nothing can be pushed to it.
  • All actions on your server are performed by Ansible playbooks you can read in /opt/n8n-agent/playbooks/.
  • The agent source is on disk at /opt/n8n-agent/src/main.go and matches the binary at /usr/local/bin/n8n-agent.

Job types it accepts

The dashboard can queue any of the following jobs. Each one maps to an Ansible playbook on your server:

  • install_n8n — deploys a new n8n instance via Docker.
  • upgrade_n8n — upgrades an existing instance to a newer version.
  • restart_n8n, stop_n8n, start_n8n — lifecycle controls.
  • backup_n8n — takes a snapshot of the n8n SQLite or Postgres data.
  • setup_ssl — provisions a Let's Encrypt certificate via Caddy.
  • health_check — verifies the n8n container is responding.
  • uninstall_n8n — removes a single n8n instance.
  • update_agent — downloads and installs the latest agent version.
  • uninstall_agent — removes the agent itself from the server.

Inspecting the agent on your server

SSH into the server as root (or with sudo) and run:

Check the version

/usr/local/bin/n8n-agent --version

Check the systemd service

systemctl status n8n-agent
journalctl -u n8n-agent -n 50 --no-pager

A healthy v2 agent logs lines like:

[n8n-agent] 2026/05/25 08:38:30 Starting n8n-agent v2.0.0
[n8n-agent] 2026/05/25 08:38:30 Registration complete

Check the configuration

cat /etc/n8n-agent/config.json

You should see the dashboard URL and your agent token. Do not share this token — anyone with it can issue jobs against your server.

Read the agent source

less /opt/n8n-agent/src/main.go

This is the exact source the binary on your server was built from.

Updating the agent

Open the Servers page. If a newer agent version is available you'll see an amber Agent Update Available box with a one-click Update Agent button.

The update flow:

  • Backs up the current binary, playbooks, and config to /opt/n8n-agent/backup/.
  • Downloads the latest installer from the dashboard.
  • Stops the agent, builds the new Go binary in place, and starts the service.
  • Verifies the new agent registered successfully — rolls back automatically if anything fails.
If the dashboard update fails, you can re-run the install command from your server's Servers page in the dashboard. It is fully idempotent and preserves your existing token and instances.

Uninstalling the agent

From the dashboard: open the server, scroll to Agent Installation, and click Uninstall Agent. This stops the service, removes the binary, the config, the systemd unit, and the /opt/n8n-agent tree.

If you no longer have dashboard access, you can uninstall manually:

systemctl stop n8n-agent
systemctl disable n8n-agent
rm -f /etc/systemd/system/n8n-agent.service
rm -f /usr/local/bin/n8n-agent
rm -rf /etc/n8n-agent /opt/n8n-agent
systemctl daemon-reload
Uninstalling the agent does not remove your n8n instances or their data. Use uninstall_n8n from the dashboard first if you want a clean teardown.

FAQ

Why Go instead of the old Bash agent?

The legacy Bash agent (1.x) shelled out to jq, python3, and curl for everything, which made metrics collection slow and error-prone. The Go agent (2.0+) is a single statically-linked binary with no runtime dependencies beyond Ansible itself — faster heartbeats, cleaner logs, and easier to debug.

Why does it run as root?

The agent manages Docker, writes to /etc, restarts services, and provisions TLS certificates. All of these need root privileges. Running unprivileged would force us to either grant blanket sudoers rules (less safe) or skip features. Standing up infrastructure-as-code tooling as root is the same model used by Ansible, Chef, Puppet, and most server management agents.

What data does it send back?

  • System metrics: CPU, memory, disk, load averages, uptime, list of Docker containers with their status.
  • n8n metrics: n8n version, workflow counts, execution counts and outcomes, webhook count, and (when enabled) Prometheus metrics from n8n itself.
  • Job logs: the output of any Ansible playbook the dashboard runs, so you can see exactly what happened.

It does not send workflow contents, n8n credentials, or any data inside your workflows.

What if my server loses internet?

Heartbeats and job polling will fail silently and retry every 30 seconds. The agent does not crash. Once connectivity is restored the dashboard will show the server as online again on the next heartbeat. Any n8n instances on the server keep running as normal.

Can one agent manage multiple n8n instances?

Yes. One agent per server is enough. The dashboard sends a different job for each instance, and the agent runs each one through Ansible against the right Docker container.