A companion process for AList v4 that pairs to a running server over an ed25519-authenticated channel and then executes delegated cross-storage-driver copy tasks on that machine — useful when the data being moved is closer to the agent than to the server (e.g. copying between two drives only reachable from a NAS/VPS the agent runs on).

• Two pairing directions — outbound (join/run: the agent dials the server with an admin-issued pairing code) and reverse (serve --pair: the server dials the agent, for agents with no inbound-reachable server)
• Short Authentication String (SAS) — both sides independently derive the same emoji sequence from the pairing exchange, so an operator can visually catch a tampered pairing before confirming it
• Encrypted, authenticated channel — every reverse connection is pinned to the server's ed25519 public key delivered at pairing time; the data listener refuses to start without one
• One task at a time — a process-wide task gate makes sure a redial racing a channel teardown can never run the same server-pushed task twice
• Bounded, single-success reverse pairing — serve --pair stays disarmed until the operator pastes a one-time token into the local pairing web, and disarms again after one success or on TTL expiry
• Live log tailing — the server can pull an agent's recent logs over the authenticated channel for troubleshooting, without shelling into the machine

go install github.com/AlistGo/alist-agent/cmd/alist-agent@latest

Or download a prebuilt binary from the Releases page.

Reverse pairing (the agent listens; the server dials in — for agents behind NAT with no server-reachable address):

1. On the AList server's admin page, issue a one-time reverse pairing token for a new agent.

2. On the agent machine, start it in serve mode with pairing armed:

   alist-agent serve --listen 0.0.0.0:5343 --pair --pair-web 127.0.0.1:5344

   --pair-web binds a local, loopback-only web page (reach it via ssh -L 5344:127.0.0.1:5344) where you paste the token the server just issued. Binding --pair-web to a non-loopback address over plain HTTP is refused unless you pass --pair-web-allow-public (the token would otherwise transit in cleartext).

3. Paste the token into that page. Once it verifies, the agent pins the server's public key and brings its data channel live.

4. Compare the SAS shown on the pairing page against the one on the server's admin page — they must match exactly — then confirm on the server. Only after that does the server start dispatching tasks to this agent.

5. On later restarts, once already paired, just run:

   alist-agent serve --listen 0.0.0.0:5343

   (re-adding --pair requires --repair too, since a persistent serve --pair must not silently re-pair on every restart).

Outbound pairing is also available for agents that can reach the server directly:

alist-agent join --host http://your-alist-server:5244 --code <pairing-code>
alist-agent run

Run alist-agent --help (or --help on any subcommand) for the full, current flag reference.

This repository is a release snapshot of the agent/ directory in the AlistGo/alist v4 monorepo. Development happens there; each tagged release here mirrors a corresponding point in the main repository's history. Projects depending on this agent should pin a tag of this repository rather than the agent/ path in the main repo.

Issues and pull requests for the agent itself are welcome on AlistGo/alist, where development on agent/ actually happens.

AGPL-3.0 — see LICENSE.