AList v4 remote agent: reverse pairing, encrypted channel, cross-drive copy executor
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 --pairstays 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@latestOr 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):
-
On the AList server's admin page, issue a one-time reverse pairing token for a new agent.
-
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-webbinds a local, loopback-only web page (reach it viassh -L 5344:127.0.0.1:5344) where you paste the token the server just issued. Binding--pair-webto a non-loopback address over plain HTTP is refused unless you pass--pair-web-allow-public(the token would otherwise transit in cleartext). -
Paste the token into that page. Once it verifies, the agent pins the server's public key and brings its data channel live.
-
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.
-
On later restarts, once already paired, just run:
alist-agent serve --listen 0.0.0.0:5343
(re-adding
--pairrequires--repairtoo, since a persistentserve --pairmust 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 runRun alist-agent --help (or --help on any subcommand) for the full, current flag reference.
| Package | Description |
|---|---|
proto |
Wire protocol: pairing handshake, SAS derivation, capability tokens, frame codec |
channel |
Transport-agnostic authenticated session layer the protocol runs over (dial + listener, handshake, encryption) |
agent |
Agent-side runtime: identity, config, heartbeat runner, reverse agent, task execution, log ring |
cli |
The join/run/serve cobra command tree, shared by this repo's cmd/alist-agent and the AList core's alist agent subcommand |
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.