Jocalsend: a peer-to-peer file sharing program using local IP subnetworking

Recently, I released a program called jocalsend, which is a play on "LocalSend". LocalSend is, in its own words, " a free, open-source app that allows you to securely share files and messages with nearby devices over your local network without needing an internet connection." You can think of it as a sort of "we have AirDrop at home", where "home" is non-Apple devices and computers. I happen to be a person without any Apple devices, and basically the only thing I ever envy about those unlike me is AirDrop, since I often want to transfer files or bits of text back and forth between my phone and computer.

LocalSend comes in the form of a cross-platform graphical app that runs on both mobile and desktop. On my Android phone, it works great, and does exactly what I'd hope it would do. On my Linux desktop, however, it requires a lot more fiddly mousing than I like to do, plus launching a GUI for what's supposed to be a low-friction, ad-hoc sharing activity is, frankly, a drag. I've always been a fan of terminal-based programs, and the terminal has been my primary interface for many, many years. It seemed natural to write a TUI version of LocalSend, and so here we are.

So, what's it good for?

Has this ever happened to you? Someone sends you a text message on your phone, and it contains a URL. You go to check it out, but it looks completely terrible on mobile, or tries to force you to install an app, or whatever; you want to use your desktop or laptop computer to look at it. But now what? Send yourself an email? Paste it into a Google Doc? Maybe you have Signal desktop so you can send yourself a Signal message then read it there. Or maybe you have an image or something on your desktop computer that you'd like to get onto your phone; your choices are basically the same as with a bit of text.

You know what all those choices have in common? They all fucking suck ass. Primarily because they require a round-trip from your local network out to a corporate data center, which means you need to be connected to the public internet. What if your internet connection is down? Well, maybe you'd be able to do something with your phone, but that means you might want to get things from your regular computer to the phone, which you can't do now. But they're also all just kinda obnoxious, aesthetically. It would be nice to just be able to directly beam the data from one thing to another, and that's what LocalSend does¹.

Something else that's nice about LocalSend is that they published a protocol spec, which means that anyone can make their own compatible implementation, which is where jocalsend comes in. I plan on writing a follow-up² about the design and implementation of jocalsend, but that's going to be a much longer and even-more-niche-interest post, so I'll just skip that for now. Stay tuned, though, if that's a boat-floater for ya!

How do I install it?

Via cargo

Jocalsend is written in Rust, a programming language released by Mozilla about ten years ago, and meant to be used for writing high-performance software in a way that was easier to do safely than in other languages like C++, but its aegis has expanded to encompass basically any and all types of software. Installing Rust on your computer is very simple.

One nice thing that Rust provides out of the box is a package manager called "cargo"³, and I think this fact alone is responsible for a big portion of Rust's success and popularity. You can use cargo to install any published Rust package that's on crates.io, the official Rust package site. Jocalsend has been published to crates.io, so if you have Rust installed, just run,

cargo install jocalsend

which will install the jocalsend program to $HOME/.cargo/bin; add that directory to you $PATH and then you can run jocalsend from the command line:

$ jocalsend -h
A TUI for LocalSend

Usage: jocalsend [OPTIONS]

Options:
  -f, --file <FILE>  File to pre-select for sending
  -t, --text <TEXT>  Text string to send
  -h, --help         Print help
  -V, --version      Print version

From nixpkgs

If you use NixOS or otherwise use nixpkgs⁴, you can also get it from there:

nix-shell -p jocalsend

and it'll do what you expect.

How do I use it?

When you first run it, you'll be on the main screen. Clockwise from the bottom, the lower left contains information about the network it's on, the lower right has a list of any LocalSend peers it discovered, the upper right has log output from jocalsend, and finally the upper left will show any incoming transfer requests, with possible text preview:

Here we can see that my phone is already available as a peer.

Receiving files and text

I can use my phone to send some text to my computer, and it will show a preview of the text even in the main screen:

If I hit r, I'll be taken to the receiving screen, where I can approve or deny the incoming transfer request, with a or d respectively:

If the incoming content is not plain text, no preview will be shown:

From nearly any screen, hitting the esc key will take you to whatever screen you were in previously.

Sending files and text

Hitting the s key will take you to the sending screen. By default, it will show a list of files from your current directory in the upper left, with log output on the right, and peers on the bottom:

Hit / to do fuzzy filename selection by entering text:

Regardless of whether or not you're doing fuzzy filename search, the up and down arrow keys will move the selection up or down, respectively.

If you'd like to send text, hit t:

then enter to send, and you can see a preview on the mobile device:

And that's all pretty much there is!

Wrapping up

Anyway, it's been pretty fun making jocalsend. I now use it daily, and every time I do, I'm pretty darned pleased with myself. If you're a weirdo like me who doesn't use Apple stuff, maybe this would be useful for you, too.