// self-host · your relay, your rules

Run your own relay.

RelayPony never puts your files on a server. The only thing that ever touches one is a tiny connection handshake for internet transfers — and you can point the app at your own box for even that.

What the relay is

On the same Wi-Fi, RelayPony finds the other device directly and sends straight to it — no server involved at all. Across the internet, the two phones still have to trade a small handshake (their network candidates) before they can open a direct connection through their routers. That hand-off is the only job of the signaling relay.

It holds each ~1 KB handshake blob for a couple of minutes, addressed by your device's public handle, until the other phone picks it up. Then the two devices connect peer-to-peer and the file flows directly between them. The relay never sees the file, and the handshake payload is opaque to it.

Why run your own

By default the app uses the relay at relaypony.app. That's fine — it can't see your files and forgets the handshake in minutes. But this is a privacy tool, so you shouldn't have to take that on faith. The relay is open source and self-hostable: run it on your own server and your transfers never depend on anyone else's box, not even for the handshake. Both devices just need to be pointed at the same relay.

Set it up

Requirements: any host that serves PHP 8+ with PDO/MySQL, plus MySQL or MariaDB.

1. Get the code

git clone https://github.com/norsehorse-dev/RelayPony-Relay.git
cd RelayPony-Relay

2. Create the database

sudo mysql -e "CREATE DATABASE relaypony_relay CHARACTER SET utf8mb4;"
sudo mysql -e "CREATE USER 'relaypony_relay'@'localhost' IDENTIFIED BY 'a-strong-password';"
sudo mysql -e "GRANT SELECT, INSERT, DELETE ON relaypony_relay.* TO 'relaypony_relay'@'localhost'; FLUSH PRIVILEGES;"
mysql -u relaypony_relay -p relaypony_relay < sql/schema.sql

3. Configure

cp config.sample.php config.php
chmod 600 config.php

Edit config.php and set the database user and password you just created.

4. Serve the `public/` directory

Point a TLS virtual host at the repo's public/ folder. The bundled .htaccess routes every request to index.php (on Apache, allow overrides; on nginx, add an equivalent rewrite to index.php). Full vhost example in INSTALL.md.

5. Test it

curl -s -X POST https://relay.example.com/api/signal \
  -d '{"op":"poll","for":"age1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzzzz"}'

A healthy relay answers {"ok":true,"blobs":[]}.

6. Point the app at it

In RelayPony: Settings → Relay server, enter https://relay.example.com. Both devices must use the same relay to find each other. That's it — your handshakes now broker through your server, and your files still go straight device-to-device, never through it.

Notes

HTTPS only. The blobs are opaque, but it's an internet endpoint; run it behind TLS.
No cron needed. Expired handshakes are cleaned up on every request.
Tiny footprint. One endpoint, one table, about 120 lines of PHP. Tuning (TTL, size caps) lives at the top of src/signal.php.

The code

Everything is public at github.com/norsehorse-dev/RelayPony-Relay, Apache-2.0. It's deliberately small enough to read in one sitting and confirm for yourself that the file transfer never passes through it.