a command-line file transfer utility for sending files from any computer to another
On macOS/Linux, if you are using Homebrew
brew install portalOn Windows, if you are using Scoop
scoop install portalOn Windows, if you are using WinGet
winget install SpatiumPortae.portalOn Arch Linux (AUR)
yay -S portal-binOn any platform, you can get the latest release manually, or simply run
curl -sL portal.spatiumportae.com | bashor
wget -qO - portal.spatiumportae.com | bashTo send files:
portal send <file1> <file2> <folder1> <folder2> ...The application will output a temporary password on the format 1-inertia-elliptical-celestial.
The sender will communicate this password to the receiver over some secure channel.
To receive those files:
portal receive 1-intertia-elliptical-celestialThe two clients will establish a connection through a relay server. The file transfer will then commence with a direct or relayed connection, depending on what's possible.
The sender (top) sends a folder and three files to the receiver (bottom).
In this case, as you can see in the event log, the transfer is made using direct transfer. That means
that the files are sent directly from one client to the other, no middlemen involved.
As it happens, these computers are in the same local network, and portal recognizes this.
portal provides:
- End-to-end encryption using PAKE2
- Direct transfer of files if possible (e.g. sender and receiver are in the same local network)
- Fallback to relay server if sender and receiver cannot connect directly
- Parallel gzip compression of files for faster and more efficient transfers
- Hosting your own relay (we'd appreciate it if you plan to send a lot of data!)
- Configurability and shell completions
- A shiny UI ⭐✨ to gaze your eyes upon while you wait for your files
portal provides extensive TAB completions for the following shells:
bashzshfishpowershell
To see installation instructions for your shell and platform, run:
portal completion [bash|zsh|fish|powershell] --helpYou probably didn't quite catch the password Bob was screaming across the room.
You can use TAB completions to auto-complete passwords on the receiving end.
Press TAB when entering parts of your password...
portal receive 42-relative-parsec-s......and portal will suggest the possible words
$ portal receive 42-relative-parsec-s...
42-relative-parsec-supernova 42-relative-parsec-scatter 42-relative-parsec-solar 42-relative-parsec-spin 42-relative-parsec-static
42-relative-parsec-sigma 42-relative-parsec-solid 42-relative-parsec-star 42-relative-parsec-storm 42-relative-parsec-systemboom. supernova.
portal receive 42-relative-parsec-supernova-y/--yes: overwrite existing files without[Y/n]prompts
-p/--port: port to host the relay server on
-r/--relay: address of the relay server (:8080,myrelay.io:1234, ...)-s/--tui-style: the style of the tui (rich|raw)
-h/--help: output help messages for any command-v/--verbose: log debug info to file
portal places its configuration file in $HOME/.config/portal/config.yml.
As evident by the file extension, the config is a simple YAML file with descriptive field names.
# The URL of the relay server.
relay: portal.spatiumportae.com
# Log debug output to file.
verbose: false
# Prompt for overwriting duplicates when receiving files.
prompt_overwrite_files: true
# The port used when serving the relay using "portal serve".
relay_serve_port: 8080
# The style of the TUI.
tui_style: richThe portal binary comes with a built-in relay server.
Spinning up your own relay is as easy as...
portal serve --port 1337The server log output is JSON. Super-recommended to run it through jq!
portal serve --port 1337 2>&1 | jq ....
{
"level": "info",
"ts": "2023-02-28T02:57:45.310134+01:00",
"caller": "rendezvous/server.go:77",
"msg": "serving rendezvous server",
"version": "v1.2.1",
"address": ":1337"
}Technical details
The connection between the sender and the server is negotiated using a intermediary server (relay).
The relay server is used to negotiate a secure encrypted channel while never seeing the contents of files nor the temporary password.
The communication works as follows:
senderconnects torelayrelayallocates a numerical ID to the sender and sends it to thesendersendergenerates and outputs the password (starting with the ID) to the terminal, hashes the password and sends it to therelayreceiverhashes the password (which has been communicated over some secure channel) and sends it to therelay- When both the
senderand thereceiverhave sent the hashed password to therelay, the cryptographic exchange starts - During the cryptographic exchange, the
relay, well, relays messages from thesenderto thereceiverand vice-versa - Once the cryptographic exchange is done, every message sent by the
senderandreceiveris encrypted, and therelaycannot see their contents - The file transfer is about to begin, and can commence in two ways:
- The
senderandreceiverare in the same local network or can be reached directly by IP in some other way- In this case, the
senderandreceiverwill happily send the files to each other directly. Therelaywill close down for this connection.
- In this case, the
- The
senderandreceiverare not on the same local network, or cannot reach each other directly. The transfer will go through therelay, which will continue to relay encrypted messages until the file transfer is completed
- The
The Makefile has everything you need.
To build a binary containing all commands, run:
PORTAL_VERSION=v1.x.x make buildIt's important to include PORTAL_VERSION, which is a semantic version string. This is needed
in order to validate senders and receivers against the relay, so transfers are disallowed
when on different major versions, for instance.
a big thank you to magic-wormhole for greatly inspiring the concept of Portal.
nhooyr/websocket, shollz/pake, charmbracelet/bubbles, charmbracelet/bubbletea, charmbracelet/lipgloss, muesli/reflow, klauspost/pgzip and many, many more.
A special thanks to our sponsors DigitalOcean.
The public relay available for everyone to use is...
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
