SnapBeam
A receiver that stays open, for getting things off your phone
Techlosoft - Device Bridge Center


WHAT IT IS
==========

You are on your phone. You screenshot something, or copy a URL, and you want
it on your PC right now. No cable, no cloud account, no emailing yourself.

SnapBeam runs on the computer and waits. Anything the phone sends lands in a
folder, is announced on the terminal, and - if it is text - is put straight on
the computer's clipboard so you can paste it.

There are two ways in, and both land in the same folder and print the same
line.

1. WITH THE LOCALSEND APP
   SnapBeam implements the LocalSend protocol v2.2, so the official LocalSend
   app finds this computer on its own. Screenshot, Share, LocalSend, tap the
   PC, done. Nothing to type but the pairing code, once.

   LocalSend is a separate project by its own authors, licensed Apache-2.0:
   https://localsend.org and https://github.com/localsend. SnapBeam is not
   LocalSend, is not affiliated with it, and contains none of its code - it
   implements the protocol they publish. See NOTICES.

2. WITH NOTHING INSTALLED
   SnapBeam draws a QR code in the terminal. Point the phone camera at it and
   the phone opens a page served by YOUR OWN computer over the local network.
   Type the six-digit pairing code once and that phone can send text, photos
   and pasted screenshots from then on. "Add to Home Screen" gives it a real
   icon and a full-screen launch.

The sibling tool PhoneBridge does the opposite job: a one-shot "put this file
on my phone" hand-off that shuts down when it is done. SnapBeam stays open and
faces the other way.


INSTALL
=======

Pre-built binaries are in dist/. There is nothing to install - copy the one for
your platform anywhere on your PATH and run it.

    dist/snapbeam-linux-amd64        Linux, x86-64
    dist/snapbeam-darwin-arm64       macOS, Apple Silicon
    dist/snapbeam-darwin-amd64       macOS, Intel
    dist/snapbeam-windows-amd64.exe  Windows, x86-64

On macOS and Linux you may need to mark it executable:

    chmod +x snapbeam-linux-amd64

To build from source you need Go 1.24 or newer. There are no dependencies of
any kind, so no network access is required:

    go build -o snapbeam .

Double-clicking the program in Explorer or Finder works: with no arguments and
a real console on both ends it asks one question - where to save things - and
then opens the receiver and stays on screen.


COMMANDS
========

    snapbeam start [--port 53317] [--dir <folder>] [--name "Study PC"]
                   [--max-size 256MB] [--host <addr>] [--allow-public]
                   [--no-localsend] [--no-code] [--qr blocks|ascii|invert]
                   [--discovery-port 53317]

    snapbeam list  [--dir <folder>] [--json]

    snapbeam peers [--seconds 5] [--port 53317] [--allow-public]

    snapbeam send  <file> [<file> ...] --to <host[:port]> [--code 123456]

    snapbeam help | -h | --help

start
    Opens the receiver and stays open until Ctrl+C. Prints the LAN address, a
    fresh six-digit pairing code, a QR code, and then a line for every item
    that arrives.

list
    What has arrived so far, newest first, with size and type. Half-finished
    ".part" transfers are shown too, marked as incomplete, rather than hidden.

peers
    Listens for LocalSend devices and lists them. This is a real discovery
    run, not just a UDP listener: it opens a throwaway HTTP server on an
    ephemeral port and announces it, because the protocol's handshake is
    two-way and a device that was already running answers an announcement by
    calling back. That throwaway server serves /register and /info only - it
    has no save folder and no upload routes, so nothing can be sent to it.
    Use it to check whether multicast works on a network before blaming
    SnapBeam.

send
    Sends files TO a LocalSend device, using the same protocol. Receiving is
    SnapBeam's job and where the care has gone; send exists because a protocol
    you can only half-speak is a protocol you cannot test.

FLAGS

    --port <n>        TCP port of the HTTP server. Default 53317, the
                      LocalSend default. The announcement tells other devices
                      which port to use, so this can be changed on its own.
    --discovery-port  UDP port of the multicast group. Default 53317. Change
                      it only to keep two receivers on one machine apart;
                      every device that should see the other must use the same
                      one.
    --dir <folder>    Where incoming items are saved. Default: a SnapBeam
                      folder in your home directory. Created if missing.
    --name <text>     The name your phone sees. Default: this machine's
                      hostname.
    --max-size <sz>   Largest single item accepted. Default 256MB. Accepts
                      256MB, 1.5G, 2TiB or a raw byte count; suffixes are
                      BINARY, so 1KB means 1024 bytes.
    --host <addr>     Bind to this address instead of the auto-detected one.
    --allow-public    Required before SnapBeam will listen on an address that
                      is not in a private range. Read SECURITY below first.
    --no-localsend    Browser page only: do not join the multicast group and
                      do not serve the LocalSend API.
    --no-code         Run with NO pairing code. Anyone on the network can then
                      send to you.
    --qr <style>      blocks (default, Unicode half-blocks), ascii for
                      terminals that cannot draw them, invert for a
                      light-background terminal.
    --code <digits>   For "send": the pairing code the far end is asking for.
    --to <host>       For "send": "192.168.1.30" or "192.168.1.30:53317".
    --seconds <n>     For "peers": how long to listen.
    --json            Machine-readable output (list).

Flags may appear before or after positional arguments; either order works.


QUICK START
===========

    # open the receiver and leave it open
    snapbeam start

    # somewhere else to save things, and a name the phone will recognise
    snapbeam start --dir ~/Screenshots --name "Study PC"

    # what has arrived
    snapbeam list

    # is multicast working on this network at all?
    snapbeam peers --seconds 8


EXAMPLE OUTPUT
==============

      SnapBeam - Study PC
      Waiting for your phone. Ctrl+C to stop.

      saving to   /home/dominic/SnapBeam
      listening   http://192.168.1.20:53317 (LAN only)
      size limit  256.0 MiB per item

      1. WITH THE LOCALSEND APP (nothing to type)
         announcing on 224.0.0.167:53317 over wlan0, HTTP on port 53317
         open LocalSend on the phone; "Study PC" appears in its list.
         screenshot -> Share -> LocalSend -> tap this computer.
         it will ask for the PIN below.

      2. WITH NOTHING INSTALLED (point the camera at this)

      [a QR code, drawn with half-block characters]
         http://192.168.1.20:53317/   (QR version 3, level M, mask 3)

      PAIRING CODE   6 7 1 5 2 2
      Type it once on the phone. Three wrong tries block that phone until restart.

    [14:44:36]  received   /home/dominic/SnapBeam/2026-08-17_144436_IMG_4821.png  (2.6 MiB, image/png)
                via LocalSend from "Dominic's iPhone"
    [14:44:41]  received   /home/dominic/SnapBeam/2026-08-17_144441_clipboard.txt  (59 B, text/plain)
                via LocalSend from "Dominic's iPhone"
                copied to the clipboard with wl-copy


SECURITY - READ THIS BEFORE LEAVING IT RUNNING
==============================================

SnapBeam is a PLAINTEXT HTTP SERVER on your local network. That is a
deliberate choice, not an oversight: browsers reject self-signed certificates,
so the phone page could not work over HTTPS without a certificate authority
nobody has at home, and the LocalSend protocol explicitly supports plain HTTP
for exactly this reason.

What that means concretely, while SnapBeam is running:

  - Everything sent to it crosses your network UNENCRYPTED. Anyone who can
    see your Wi-Fi traffic - another guest on a hotel or cafe network, someone
    with the password, a compromised router - can read the screenshots and
    text you send, and can read the pairing code as it goes past.
  - It announces itself by multicast. Every device on the network segment can
    see that this computer is here, what it is called, and which port it is on.
  - Anyone on the network can reach the port. The pairing code is what stops
    them putting files on your disk; it is not encryption and it never becomes
    encryption.

WHO SHOULD NOT USE THIS

  - Anyone on a network they do not control: hotels, cafes, airports, shared
    student halls, conference Wi-Fi, guest networks at a client's office.
  - Anyone sending material that would matter if a stranger read it: medical
    or legal documents, credentials, anything covered by a confidentiality
    obligation, anything under GDPR or HIPAA.
  - Anyone who needs an audit trail of who sent what. SnapBeam records the
    sender's alias, which the sender chose, and their IP address. Neither is
    proof of anything.

WHAT SNAPBEAM DOES TO LIMIT THE DAMAGE

  - It refuses to listen on a publicly routable address. It enumerates the
    machine's interfaces, keeps the IPv4 addresses that are up, not loopback
    and not point-to-point, and binds to a PRIVATE one (10/8, 172.16/12,
    192.168/16, 100.64/10 or 169.254/16). If none of them is private it prints
    what it found and exits rather than opening the socket. --allow-public is
    the only way past that, and --host 0.0.0.0 needs it too.
  - Every upload endpoint requires the pairing code, on both paths: as the
    protocol's ?pin= query parameter for LocalSend, and as an X-SnapBeam-Code
    header for the browser page. It is compared with
    crypto/subtle.ConstantTimeCompare over the SHA-256 of each side, so the
    comparison takes the same time for a wrong code of any length.
  - The code is fresh every run, drawn from crypto/rand with rejection
    sampling so all million codes are equally likely.
  - Three wrong codes from one address and that address gets HTTP 429 until
    SnapBeam is restarted. A correct code before the third clears the count.
  - The pairing code travels in the QR code as a URL FRAGMENT (#123456).
    Browsers never send a fragment to any server, so scanning the code cannot
    write it into an HTTP log on the way.
  - The pairing code is never printed to the log, never written to a file, and
    never appears in an error message. Neither are file contents.
  - Every incoming filename is sanitised before it touches the disk (see
    below) and every upload is capped (--max-size).
  - Files are written to "<name>.part" and renamed on success, so a
    half-finished transfer is never mistaken for a complete file.
  - One transfer session at a time, as the protocol requires; a session whose
    sender goes quiet for five minutes is released so a crashed phone cannot
    lock the receiver out.
  - The phone page makes NO external requests of any kind - no CDN, no font,
    no analytics - and says so in a Content-Security-Policy that forbids them.

FILENAME HANDLING

A filename arriving over the network is treated as hostile input. SnapBeam
keeps only ASCII letters, digits, space, dot, dash and underscore; everything
else becomes an underscore, and every kind of whitespace becomes one space.
That is an allow-list, not a list of bad sequences, which is why it also
disposes of Unicode look-alike attacks - a fullwidth solidus, a fraction
slash, a division slash or a right-to-left override is simply not on the list.
Path components are stripped first, "." and ".." become "untitled", leading
dots are removed, trailing dots and spaces are trimmed, Windows device names
(con, nul, com1, lpt9 and the rest, with or without an extension) get an
underscore in front, and the result is capped in length.

NOTHING IS EVER DELETED OR OVERWRITTEN

Incoming files get a timestamped name. If that name is taken, SnapBeam inserts
-2, -3 and so on before the extension until it finds a free one. It never
overwrites. The only file SnapBeam ever deletes is a ".part" file it created
itself moments earlier and could not finish.


HOW THE LOCALSEND COMPATIBILITY WORKS
=====================================

SnapBeam implements protocol version 2.2 as published at
https://github.com/localsend/protocol.

DISCOVERY (protocol section 3)
    SnapBeam joins 224.0.0.167:53317 on every multicast-capable interface and
    sends an announcement burst of three datagrams (at 100ms, 500ms and 2s,
    matching the reference implementation), then repeats once a minute so a
    phone that wakes up later still finds it. The datagram is exactly:

        {"alias":"Study PC","version":"2.2","deviceModel":"Linux",
         "deviceType":"desktop","fingerprint":"<64 hex chars>","port":53317,
         "protocol":"http","download":false,"announce":true}

    When another device announces itself, SnapBeam answers over HTTP by
    POSTing its own descriptor to that device's
    /api/localsend/v2/register. That HTTP call is what puts SnapBeam in the
    other device's list.

ENDPOINTS IMPLEMENTED
    POST /api/localsend/v2/register        section 3.1, 3.2
    GET  /api/localsend/v2/info            section 6.1
    POST /api/localsend/v2/prepare-upload  section 4.1
    POST /api/localsend/v2/upload          section 4.2
    POST /api/localsend/v2/cancel          section 4.3

    Status codes follow the tables in the document: 204 when there is nothing
    to transfer, 400 for a bad body or missing parameters, 401 for a missing
    or wrong PIN, 403 for a rejection or a bad token, 409 when another session
    holds the slot, 422 when a declared SHA-256 does not match what arrived,
    429 after three wrong PINs.

FINGERPRINT (section 2)
    SnapBeam runs plain HTTP, so its fingerprint is a random 32-byte value
    generated at startup, as the document specifies for that case. It
    identifies a running receiver, never the machine across restarts.

TWO PLACES THE SPECIFICATION IS AMBIGUOUS, AND WHAT SNAPBEAM DOES

    The "announce" flag. The published document shows "announce": true on an
    announcement and describes an optional UDP reply carrying
    "announce": false. The current reference implementation serialises the
    flag when sending but does not read it back, and never replies over UDP at
    all. SnapBeam follows the document: it sends "announce": true, treats a
    message with the flag missing as an announcement, and never answers one
    that says "announce": false. That last rule is what stops two receivers
    answering each other in a loop forever. SnapBeam does not send UDP
    replies either; the HTTP register call is the reply.

    The checksum field name. The document calls it "sha256". The Dart client
    that shipped for years encodes it as "hash". The current Rust core uses
    "sha256". SnapBeam accepts either on the way in and verifies whichever it
    was given.

NOT IMPLEMENTED FROM THE PROTOCOL, DELIBERATELY

    - The download / reverse-transfer API (sections 5.1 to 5.3). SnapBeam is a
      receiver. It advertises "download": false and means it.
    - HTTPS and the mTLS certificate pinning the newer LocalSend builds use.
      SnapBeam announces "protocol":"http", which the protocol supports and
      which the LocalSend client honours per peer.
    - Protocol v1 routes (/api/localsend/v1/...). They return 404 rather than
      a half-right answer. v1 announcements are understood well enough not to
      be answered incorrectly.
    - IPv6 discovery. The current LocalSend app additionally announces on
      ff12::fd3a:e420 as an extension on top of v2.2; SnapBeam is IPv4 only.


THE QR CODE
===========

The QR encoder is written here, in the standard library, from ISO/IEC 18004.
It covers byte mode, versions 1 to 10, and all four error-correction levels -
up to 271 bytes at level L, against the roughly 33 bytes a pairing URL needs.
A payload that will not fit produces an error, never a silently truncated
symbol, because a truncated QR code scans perfectly and sends the phone to the
wrong place.

It includes the Reed-Solomon codewords over GF(256) with primitive polynomial
0x11D, the BCH(15,5) format information with its 0x5412 mask, the BCH(18,6)
version information on versions 7 and up, block interleaving, and the
penalty-driven choice of one of the eight mask patterns, scored on the
complete symbol as section 8.8.2 specifies.

The tests compare the finished module matrix against reference matrices
produced by an unrelated implementation, and check the format bits and version
bits against the standard's own tables and the error-correction codewords
against the worked example in its Annex I.

Rendering is Unicode half-blocks by default, two module rows per text line,
drawn so that LIGHT modules appear in the terminal's foreground colour. That
is the right way round on the usual light-on-dark terminal. On a
light-background terminal use --qr invert; where block characters do not
render at all, --qr ascii.


THE PHONE PAGE
==============

One file, embedded in the binary, with the HTML, CSS and JavaScript inline and
no external request of any kind - which is not a style preference but a
requirement, because the phone has no internet route to your PC's server.

It asks for the pairing code once and remembers it in localStorage. It offers
three ways to send: type or paste text, pick images from the photo library,
and paste an image straight from the clipboard. It shows a live list of what
has been sent with a progress bar and a tick when the computer confirms
receipt. Touch targets are at least 56 pixels, there is no hover-only
interaction and no small text.

It carries a web app manifest and an apple-touch-icon, so "Add to Home Screen"
gives a real app icon and a full-screen launch on both iPhone and Android.

One honest limitation: navigator.clipboard.read() requires a secure context,
and a plain-HTTP page on a LAN is not one in Chrome. The button that reads the
clipboard directly therefore works in some browsers and not others. Where it
does not, the page says so and points at the route that always works: paste
into the text box, which catches an image on the paste event and sends it the
same way. On iOS Safari the paste event is the normal route anyway.


SCOPE / WHAT THIS DOES NOT DO
=============================

THERE IS NO NATIVE PHONE APP, AND NONE WAS BUILT

Be clear about what you are getting. There is no Xcode and no Android SDK in
the environment SnapBeam was built in, so no App Store or Play Store app could
be produced, and none was. Nothing here is a native iOS or Android
application.

What you get on the phone instead is two real things:

  - The official LocalSend app, which IS a native app on both stores, written
    and maintained by the LocalSend project. SnapBeam speaks its protocol so
    that app can talk to your computer. That is the polished client, and it is
    not ours.
  - An installable home-screen web app that SnapBeam serves itself. It is a
    genuine, working phone client on both platforms and needs no app store,
    but it is a web page: it runs in the phone's browser engine with a browser
    engine's permissions.

A native SnapBeam app would add: sharing directly from the iOS or Android
share sheet without opening a page first; background transfer that survives
the screen locking; push notification when a transfer completes; access to the
photo library at full resolution without the browser's re-encoding;
Handoff-style automatic pairing; and a place in the app switcher. None of that
is possible from a web page, and none of it is implemented here.

WHAT WAS NOT TESTED

SnapBeam's LocalSend implementation has been tested against ITSELF - two
copies on one machine discovering each other over real multicast and
completing real transfers - and against the published specification, field by
field. It has NOT been tested against the official LocalSend app on a real
phone, because there is no phone and no app store in the build environment.
The wire format matches the document; whether every build of every client is
happy with it is something to confirm on your own network before relying on
it. If it does not work, `snapbeam peers` and the terminal log are where to
look first.

ALSO NOT IMPLEMENTED

  - Encryption of any kind. See SECURITY above. There is no HTTPS, no TLS, no
    end-to-end encryption, and no plan to pretend otherwise.
  - Authentication beyond one shared six-digit code. No accounts, no per-device
    keys, no revocation, no remembering which phones you trust between runs.
  - The LocalSend download API, so a phone cannot pull files FROM this
    computer over the protocol. Use the sibling tool PhoneBridge for that.
  - Resuming an interrupted transfer. A transfer that dies leaves a .part file
    and must be started again.
  - Compression, deduplication, or any processing of what arrives. Bytes land
    on disk exactly as they were sent.
  - Any kind of history, index or database. `list` reads the folder.
  - Background operation. SnapBeam never daemonises, never installs itself,
    never adds a startup item and never runs as a service. It is a program in
    a window; close the window and it stops.
  - Automatic firewall configuration. If your machine's firewall blocks
    inbound TCP 53317 or UDP multicast, you must allow it yourself.
  - Discovery across subnets or over a VPN. Multicast does not cross routers.
    Point-to-point interfaces are deliberately excluded from address
    selection, which means a VPN address is never chosen.
  - IPv6, anywhere. Addresses, binding and discovery are IPv4 only.
  - Clipboard images. Text that arrives goes on the clipboard where the OS
    provides a tool for it; an image that arrives is saved to the folder and
    not placed on the clipboard.
  - Windows code signing and macOS notarisation. These are unsigned indie
    builds, so SmartScreen and Gatekeeper will warn on first run.


EXIT CODES
==========

    0   Success. `start` exits 0 when it is stopped with Ctrl+C, having done
        its job for as long as it ran. Explicit help exits 0.
    1   Bad invocation (unknown command, missing required flag, unparseable
        size), a refusal to bind to a public address without --allow-public,
        or an I/O error (cannot create the save folder, port already in use,
        no usable network interface).


WHERE THINGS ARE SAVED
======================

Default: a folder called SnapBeam in your home directory. Override with --dir.

Names are "<date>_<time>_<the name the sender gave, sanitised>", for example:

    2026-08-17_144436_IMG_4821.png
    2026-08-17_144436_clipboard.txt
    2026-08-17_144436_clipboard-2.txt     <- second item in the same second

Text sent from the browser page with no name of its own lands as note.txt.
Text sent through LocalSend keeps whatever name the app gave it.


CLIPBOARD
=========

Text that arrives is put on the system clipboard when the operating system
provides a tool to do it: clip.exe on Windows (and from WSL), pbcopy on macOS,
wl-copy or xclip or xsel on Linux. There is no portable way to do this from Go
without linking against the platform's window system, so SnapBeam shells out
to what is already there.

If none of those is present - a headless server, a bare container, a Linux box
with no display - the transfer still succeeds and the terminal says so:

    no clipboard tool on this machine - saved to /home/dominic/SnapBeam/...

A missing or broken clipboard NEVER fails a transfer. The file is already on
disk by the time the clipboard is touched. Only text is copied, and only up to
256 KiB of it; a large log file is a file, not a snippet.