Send Files and Messages Between Machines
Move a file, a message or a notification from one of your machines to another, wherever they are. Nothing gets a public link: the other machine has to be online under a name, with a key of your account.
Goal
From your laptop: send report.txt to work-laptop, send it a message and get the reply, and pop up a notification on it.
Prerequisites
- Two machines of your account (your laptop, and
work-laptop) with thenfltrCLI. Each command below names a service of the other machine as<machine>.<service>(work-laptop.inbox); a bare service is the same machine's. - Each with its own API key of your account, saved with
nfltr config add-api-key. One key runs one connection at a time, so the receiving machine needs its own key. - For the clipboard (step 4) on Linux:
xclip,xselorwl-clipboard(wl-copy/wl-paste) on each machine whose clipboard nfltr reads or writes. macOS and Windows need nothing extra. Without one,clipboard listenprintsListening as work-laptop, but copies and pastes will fail: no clipboard tool found ….
1. Send a file (peer to peer)
On work-laptop, wait for a file:
$ nfltr p2p recv --name drop --output ./inbox
[p2p] listening as drop — waiting for incoming P2P connection…
On your laptop, send it:
$ echo "Q3 numbers: 42" > report.txt
$ nfltr p2p send report.txt work-laptop.drop
[p2p] end-to-end encrypted, session fingerprint 4F2A-91C0-7D3E-22B8-A15C (compare it with the other machine: …)
[p2p] connecting (direct TCP and WebRTC)…
[p2p] data path: tcp-direct (tcp, 192.168.1.9:52558 → 192.168.1.20:52551)
[p2p] sending file "report.txt" (15 B)…
[p2p] [████████████████████] 100% (15 B / 15 B)
[p2p] ✓ transfer complete (15 B in 0.0s, 1.2 KB/s)
The file is end-to-end encrypted between the two machines on every path, the relay and a TURN server included: the machines agree on a fresh key through the relay, which sees only their public keys, and the file's name, size and contents travel encrypted. The relay still sees which machines connect, when, that it is a file transfer, how many bytes flow and when, and the addresses the machines offer each other for a direct connection. Both machines print the same session fingerprint; if the two differ, something between them (the relay) replaced the keys. With a pairing key on both machines (--e2ee-key-file) that cannot happen unnoticed: the transfer is refused instead. Chat (p2p chat) and calls work the same way.
data path: says which way the file went: a direct TCP connection on the same network (tcp-direct), and a WebRTC data channel through NAT routers that keep one public port per local port, which most home routers do (webrtc-srflx). When a symmetric NAT sits in front of either machine (common on mobile carriers and some company networks), no direct path exists: with your own TURN server (--turn, below) the file goes through it (webrtc-turn), and otherwise through the relay after up to 10 seconds trying (relay). Every path checks the file's SHA-256 before saving it. --force-relay always uses the relay. work-laptop prints ✓ saved to "inbox/report.txt" and exits (--keep keeps it waiting for more; --from you-laptop accepts only one sender). A directory works the same way: nfltr p2p send ./data/ work-laptop.drop.
$ cat inbox/report.txt
Q3 numbers: 42
2. Send a message and get a reply
Messages are always end-to-end encrypted with a key only your machines hold. Your hub's machine has one already (nfltr orch hub makes it, and nfltr orch hub machines add <machine> --out one for each other machine, see nodes). Without a hub, make one and copy it to the other machine yourself, never through nfltr:
$ f=~/.config/nfltr/a2a-root.key; mkdir -p ~/.config/nfltr && [ -f $f ] || (umask 077; openssl rand -hex 32 > $f)
$ scp ~/.config/nfltr/a2a-root.key work-laptop:.config/nfltr/a2a-root.key
On work-laptop, listen. By default every message is printed and echoed back; --exec 'jq .command' answers with a command's output instead:
$ nfltr a2a listen --name inbox
Listening as inbox for incoming A2A calls... (Ctrl+C to stop)
On your laptop:
$ nfltr a2a send work-laptop.inbox "deploy finished"
Connected as laptop-1f2e, sending to m-5keeepem74hr5ipmm64zvsq5hy-inbox...
deploy finished
work-laptop prints [you.you-laptop] deploy finished. Pipe data in instead of an argument:
$ echo '{"cmd":"status"}' | nfltr a2a send work-laptop.inbox
{"cmd":"status"}
Without the key the relay can neither read a message nor sit in the middle (end-to-end keys). nfltr a2a list shows which of your machines are online.
$ nfltr a2a list
Connected agents (2):
m-5keeepem74hr5ipmm64zvsq5hy-inbox (a2a, a2a-e2ee)
m-q2wd7tmrsvbbo3e7l4yj3kgpxa-node-build-box (a2a, node, a2a-e2ee) [nfltr.agent.claude=available, nfltr.machine_id=build-box, nfltr.node.harnesses=claude-code, nfltr.node.id=build-box, nfltr.node.max_agents=2, nfltr.node.monitors=allowed, nfltr.runtime=node]
Send a message:
nfltr a2a send m-5keeepem74hr5ipmm64zvsq5hy-inbox "hello"
It lists everything your account has online, on any of its machines (here also a node from Join machines as nodes), each with its capabilities in ( ) and its labels in [ ]. Each is listed by its ref, <machine id>-<service> (nfltr machines shows which machine an id is); a2a send takes a ref or <machine>.<service>.
3. Send a notification
$ nfltr notify send work-laptop.inbox "Build finished" --title CI
Notification sent to m-5keeepem74hr5ipmm64zvsq5hy-inbox
A machine running nfltr notify listen shows it as a desktop notification (step 5). The a2a listen from step 2 prints it instead: [you.you-laptop] notify:CI:Build finished. Pipe the text in for scripts: npm test && echo "tests passed" | nfltr notify send work-laptop.notify.
# Ctrl+C in the nfltr a2a listen terminal on work-laptop
4. Share a clipboard
Put text on work-laptop's clipboard, and fetch its clipboard back into yours. On work-laptop, receive copies. --allow-paste also lets your machines read its clipboard; without it, pastes are refused:
$ nfltr clipboard listen --name clipboard --allow-paste
Receiving clipboard copies as clipboard; pastes allowed
On your laptop, the target comes first:
$ nfltr clipboard copy work-laptop.clipboard "staging password rotated at 14:05"
Copied 33 bytes to work-laptop.clipboard's clipboard
$ nfltr clipboard paste work-laptop.clipboard --stdout
staging password rotated at 14:05
Without text, clipboard copy sends your current clipboard (or piped input: cat notes.txt | nfltr clipboard copy work-laptop.clipboard). Without --stdout, clipboard paste writes to your clipboard.
# Ctrl+C in the nfltr clipboard listen terminal on work-laptop
5. Receive desktop notifications
On work-laptop, leave this running; each nfltr notify send work-laptop.notify … from any of your machines shows up as a desktop notification:
$ nfltr notify listen --name notify
Listening for notifications as notify...
$ nfltr notify send work-laptop.notify "Deploy finished" --title CI
Notification sent to m-5keeepem74hr5ipmm64zvsq5hy-notify
# Ctrl+C in the nfltr notify listen terminal on work-laptop
6. Call another machine
With nfltr p2p recv --name drop running there, nfltr p2p call work-laptop.drop opens a call page in the browser on both machines: audio, video, screen sharing and chat. Signaling and chat start through the relay at once, so the call connects in a few seconds wherever the machines are, and also use a direct connection between the two machines when one comes up. Audio and video go straight between the two browsers (WebRTC) and connect when the machines share a network, or when the NAT in front of each keeps one public port per local port (most home routers). When a symmetric NAT sits in front of either machine (common on mobile carriers and some company networks), audio and video need a TURN server to relay them. nfltr.xyz does not provide one: the page then says Direct video connection failed — text chat still works, and chat keeps working.
If you run your own TURN server, give it to both sides: nfltr p2p call work-laptop.drop --turn turn:turn.example.com:3478 (or nfltr p2p send report.txt work-laptop.drop --turn … for a file) and nfltr p2p recv --name drop --turn turn:turn.example.com:3478, with the username and password in NFLTR_TURN_USERNAME and NFLTR_TURN_CREDENTIAL (never on the command line). Calls and files then fall back to relaying through it only when no direct path works.
Clean up
Stop every listener with Ctrl+C. p2p recv without --keep has already exited.
If it goes wrong
| You see | Meaning and fix |
|---|---|
Error: rpc error: code = NotFound desc = target agent not connected | Nothing listens under that name. Start a2a listen (or notify listen) there, and check the --name. |
Error: peer "nobody-here" not found after a few retries | p2p send found no p2p recv under that name. Start the receiver first. |
Error: work-laptop is not running `nfltr clipboard listen` … | Something else (an a2a listen, for example) answers under that name. Run nfltr clipboard listen there. |
Error: work-laptop: this machine does not share its clipboard … | Its clipboard listen runs without --allow-paste. Restart it with the flag to allow pastes. |
this session was replaced by a newer one with the same agent ID and key | Both machines run under the same name with the same key. Give each machine its own --name. |
no A2A E2EE key on this machine (A2A is end-to-end keyed only) | This machine has no key yet. Make or copy one as in step 2. |
peer's A2A E2EE key failed pairing-key verification | The two machines have different pairing key files. See pairing keys. |
end-to-end key check failed: the two machines use different A2A keys (p2p) | Only one machine has --e2ee-key-file, the files differ, or the relay replaced the keys or rerouted the session. Give both machines the same file (or one the root key and the other its machine key), or neither. |
p2p files, chats and calls need nfltr v2.1.47 or newer on both machines (p2p protocol 4) | The other machine runs an older nfltr, which speaks an older p2p protocol. Upgrade it (nfltr update). |