LuxDrop

LuxDrop (luxdrop, package luxdrop) sends files, folders and text securely to devices on the same local network. It speaks two protocols:

  • LuxDrop protocol (LuxOS ↔ LuxOS): TLS 1.3, pinned keys and a 6-digit verification code. This is the default whenever both sides run LuxOS. The Android app LuxOS Companion (0.3 and newer) speaks it too – see Android phone.
  • LocalSend protocol v2 (v2.2, compatible with 2.0/2.1): for the LocalSend app on Android, phones and tablets, Windows and other Linux systems. It uses HTTPS with mutual TLS.

The full specification is in /usr/share/doc/luxdrop/PROTOCOL.md.

GUI

Run luxdrop (Launchpad: LuxDrop), or luxdrop FILE… to open it with files already selected. In Files (Thunar), right-click › Send To › LuxDrop (/usr/share/Thunar/sendto/luxdrop.desktop).

  • Send: "Choose what to send or drop files here, then tap a device". You can pick Files, a Folder, Text, or Paste from the clipboard.
  • Nearby devices: LuxOS computers (mDNS _luxdrop._tcp) and LocalSend apps (multicast). Use Refresh, Scan the local network (finds LocalSend devices when multicast is blocked) or Connect by address… (IP of the other device).
  • Receive: a "Ready to receive" switch, and Who can send: Everyone nearby, Trusted devices only, or receiving off ("Receiving is turned off. Other devices cannot see this computer."). Recently received files have "Open folder" and "Show in folder".
  • Settings:
  • Device name, Save to (folder).
  • Quick save: save files from trusted LuxOS computers without asking (LocalSend devices are always asked).
  • Receive when LuxDrop is closed: enables the background service. Requests then appear as notifications.
  • Work with LocalSend apps (port 53317), PIN for LocalSend senders.
  • Trusted devices (Remove), and the key fingerprint of this computer.
  • Security notes.

Verification code and trust

When two LuxOS computers meet for the first time, both screens show the same 6-digit code (e.g. 972 316). The receiver must click Accept, and the sender must confirm that the receiver shows the same code. Only then is data sent. "Trust this device" (on by default) pins the other computer's key. After that no code is shown, and with Quick save the transfer is accepted automatically.

If a trusted device later shows a different key, the transfer is aborted with key_mismatch ("someone may be impersonating the device"). There is no fallback to code pairing. To pair again, first remove the device from Trusted devices (luxdrop trust remove <ID>).

LocalSend has no verification code, and LocalSend devices announce themselves on the network without any proof of who they are - anyone nearby can use any device name. LuxDrop therefore treats LocalSend devices as not verified:

  • In the device list they carry a Not verified badge (LuxOS computers paired with the code do not). The tooltip, the accept dialog and the notification show a short device code - the first 16 characters of the device's certificate fingerprint (e.g. 4BAD DE53 A7F7 CDEE) - which you can compare with the fingerprint shown on the other device (luxdrop id on LuxOS).
  • Files from a LocalSend device are never saved without asking, even when the device is trusted and Quick save is on. "Trust this device" (off by default for LocalSend) only lets the device send in the "Trusted devices only" mode.
  • After the first accepted transfer (or the first successful send to it) LuxDrop remembers the key of the device with that name (localsend_pins.json). If a device with the same name later shows a different key (or no certificate at all), LuxDrop warns loudly: the device list shows Key changed, sending needs "Send anyway", and receiving needs the box "I have checked that it really is this device" before Accept works (on the command line you must type yes; the notification has no Accept button). Accepting the new key replaces the remembered one - do it only when you know the device was reinstalled or reset.

Plain-HTTP LocalSend devices (encryption turned off in LocalSend) are shown as "Unencrypted", and nothing is sent to them or accepted from them.

Who may send (receive modes)

Mode Trusted device Unknown device
off refused refused
trusted allowed (LuxOS: auto-saved with Quick save, otherwise asked; LocalSend: always asked) refused without asking
everyone (default) allowed you must Accept after comparing the code

everyone can be limited in time (at most 10 minutes, then back to trusted). Every transfer from an unknown device always needs an explicit Accept. A request expires after 120 s. The same policy applies to LocalSend senders, who can additionally be required to enter a PIN.

Command line

luxdrop                                  # GUI (also: luxdrop gui, luxdrop FILES…)
luxdrop devices [--timeout 3] [--scan]   # list nearby devices (--scan: also scan the LAN for LocalSend)
luxdrop send TARGET FILE…                # TARGET = device name, ID, HOST[:PORT] or NAME@HOST[:PORT]
luxdrop send TARGET --text "hello"       # send a text message
luxdrop send TARGET FILE --localsend     # send to a LocalSend device (phone, Windows, …)
     [--pin PIN] [--port N] [--no-remember] [-q]
luxdrop receive [--mode off|trusted|everyone] [--minutes N] [--dir DIR] [--port N] [--bind ADDR]
                [--no-mdns] [--ls-port N] [--no-localsend] [--no-multicast] [--pin PIN]
luxdrop trust [list]                     # trusted devices
luxdrop trust remove ID|NAME
luxdrop id                               # this device's name and key fingerprint
luxdrop mode [off|trusted|everyone] [--minutes N]

When sending in a terminal, luxdrop send prints the receiver and the verification code and asks "[y]es and remember / [o]nly this time / [N]o". Exit codes: 0 ok, 1 failure, 2 usage, 3 declined, 4 key problem.

Files of another computer

LuxDrop can also open the shared folders of another LuxOS computer in Files, side by side with your own files (drag & drop copies between the computers). The other computer turns on Settings › Share folders (only Public by default) and must allow each new computer: Allow once, Always allow or Deny. Access is read-only unless the owner also allows changes. See Files of another computer.

luxdrop connect [TARGET] [--write] [--no-open] [--port N]   # without TARGET: "Connect to Computer" window
luxdrop disconnect [NAME | --all]
luxdrop connections
luxdrop share [status | on | off | add FOLDER [--yes] | remove FOLDER]
luxdrop share forget|allow-write|read-only ID

Android phone (LuxOS Companion)

The LuxDrop tab of the Android app LuxOS Companion (0.3 or newer, Android 10+) uses the LuxDrop protocol – the same encryption, pinned keys and verification code as between two LuxOS computers, not the LocalSend mode. It needs only the same Wi-Fi or hotspot, not Bluetooth.

  • Phone → computer: turn receiving on in LuxDrop on the computer. Run luxdrop id (or open Settings › Security) and type or paste the whole key fingerprint into the app, together with the computer's IP address and port 47923. The app checks the key before it sends anything; a wrong or changed key stops the transfer. On the first transfer the computer shows the verification code – compare it with the phone and Accept. The app sends one file at a time; an interrupted transfer continues where it stopped.
  • Computer → phone: in the app, turn on receiving (for 10 minutes). The phone then appears in LuxDrop under Nearby devices (or use Connect by address with the phone's IP). Compare the code on both screens; the phone always asks before it accepts. The phone takes at most 16 files and 1 GiB per transfer and no folders. From app 0.3.1 LuxDrop then says why ("Too many files or too much data for the receiver", "Not enough disk space", folders refused as invalid); with 0.3.0 a bigger offer ends with "connection lost". Received files stay encrypted in the app until you export them.
  • From app 0.3.1 the phone can search the network for computers to fill in the address and port (you still enter the whole key fingerprint – mDNS data is not trusted). The computer finds the phone over mDNS only while the phone is receiving.
  • From app 0.3.1 the app accepts the TLS suites AES-256-GCM and ChaCha20-Poly1305 (0.3.0 accepted only AES-256-GCM). LuxOS prefers AES-256-GCM as a receiver; as a sender it offers AES-256-GCM first, and a phone without AES hardware may pick ChaCha20, which is faster there.

Background receiving

The user service luxdrop-receiver.service runs luxdrop receive --service. Turn it on with "Receive when LuxDrop is closed" in Settings, or with systemctl --user enable --now luxdrop-receiver.service. Accept requests appear as notifications, or as a dialog when a display is available.

Files and folders

What Where
Received files ~/Downloads/LuxDrop (XDG download folder + LuxDrop), or the folder from Settings
Partial downloads <download folder>/.luxdrop-partial/ (verified by SHA-256 before being moved into place; existing files are never overwritten, names get " (1)")
Settings ~/.config/luxdrop/settings.json (name, receive_mode, download_dir, port, background, auto_accept_trusted, localsend, localsend_port, pin)
Identity key and certificate ~/.local/share/luxdrop/identity-key.pem, identity-cert.pem (EC P-256)
Trusted devices, history ~/.local/share/luxdrop/trusted.json, history.json
Remembered LocalSend device keys ~/.local/share/luxdrop/localsend_pins.json (name → key; delete the line or the file to forget a device)
Shared folders, computers with access ~/.config/luxdrop/shares.json, ~/.local/share/luxdrop/file-access.json

Ports and firewall

Port Use
TCP 47923 LuxDrop protocol (receiver)
TCP 47924 Shared folders (only while sharing is on)
TCP 53317 LocalSend HTTPS server
UDP 53317 LocalSend multicast discovery, group 224.0.0.167 (link-local)
UDP 5353 mDNS (Avahi)

The LuxOS firewall (firewall.md) opens these ports automatically while LuxDrop listens on them (47924 only while sharing is on), only for this network (private addresses and networks the computer is connected to; also ports changed in LuxDrop's settings). From the internet and over VPNs they stay closed; over Tailscale only with Treat Tailscale devices as this network in Settings › Firewall. If you use ufw or firewalld instead, allow the ports only on private networks; the package includes a firewalld service and a ufw profile:

sudo firewall-cmd --permanent --zone=home --add-service=luxdrop && sudo firewall-cmd --reload
sudo ufw allow from 192.168.0.0/16 to any app LuxDrop

Troubleshooting

  • No LuxOS computers found: avahi-daemon must be running (the app says so when it is not): systemctl status avahi-daemon.
  • Port in use: "Cannot receive from LuxOS computers: port 47923 is in use". Another LuxDrop instance (for example the background receiver) is probably running.
  • Devices not visible on guest Wi-Fi (client isolation, no multicast): use Scan the local network or Connect by address.
  • LocalSend compatibility missing: it needs the python-pyopenssl package.
  • "key_mismatch": the other device has a new key (reinstall) or someone is impersonating it. Check it, then remove the old trust entry and pair again.