Ruroco is a tool that lets you execute commands on a server by sending UDP packets. The commands are configured on the server side, so the client does not defin
Ruroco is a tool that lets you execute commands on a server by sending UDP packets. The commands are configured on the server side, so the client does not defin
ruroco is a tool that lets you execute commands on a server by sending UDP packets.
It triggers a pre-configured action on the server (open a firewall rule, restart a service, run a script) — it is not a tunnel or a VPN. There is no session, no connection, and no traffic carried: the client fires a single stateless packet and the server runs a whitelisted command. In other words, ruroco grants a capability to act without granting network access. See ruroco vs WireGuard / VPN for when that matters and when a plain VPN is the better choice.
the tool consist of 4 binaries:
ruroco-client: runs on your notebook/computer and sends the UDP packetsruroco-client-ui: presents most of the functionality of ruroco-client in an easier to use user interface.ruroco-server: receives the UDP packets and makes sure that they are validruroco-commander: runs the command encoded by the data of the UDP packet if it's validThe commands are configured on the server side, so the client does not define what is going to be executed, it only picks from existing commands.
Download binaries from the releases page or build them yourself by running
make releaseyou can find the binaries in target/release/client, target/release/client_ui, target/release/server and
target/release/commander
yay -S ruroco-clientSee make goal install_client. This builds the project and copies the client binary to /usr/local/bin/ruroco-client
Run the following script
curl -Ls "$(curl -s https://api.github.com/repos/beac0n/ruroco/releases/latest | grep -oE 'https://[^"]*/client-v[0-9]+\.[0-9]+\.[0-9]+-x86_64-linux')" -o ~/.local/bin/ruroco-client
chmod +x ~/.local/bin/ruroco-client
~/.local/bin/ruroco-client update --forceyay -S ruroco-client-uiyay -S ruroco-serverAfter installing, generate a shared key, place it in /etc/ruroco/, and edit /etc/ruroco/config.toml.
See make goal install_server, which
~/.local/bin//usr/local/bin/ruroco-client wizard.key file and copy it to the right placeconfig.tomlsystemctl start ruroco.service. The wizard deliberately leaves it stopped until a
.key exists, since a keyless server exits at startup and Restart=always would crash-loop it into systemd's
start limitRun the following script
curl -Ls "$(curl -s https://api.github.com/repos/beac0n/ruroco/releases/latest | grep -oE 'https://[^"]*/client-v[0-9]+\.[0-9]+\.[0-9]+-x86_64-linux')" -o ~/.local/bin/ruroco-client
chmod +x ~/.local/bin/ruroco-client
~/.local/bin/ruroco-client update --force
sudo ~/.local/bin/ruroco-client wizardSee nix/android.nix, scripts/dev_ui_android.sh and scripts/release_android.sh
See SECURITY.md for the full threat model: in-scope attacks, accepted risks, key lifecycle (generation, rotation, revocation), and the supported-versions table.
ruroco-client-uiUse the Generate Key action (or ruroco-client gen) to produce a base64-encoded shared key. Copy that key into the
server's .key files (see server config) and reuse the same string with ruroco-client send. You can save your key
safely in a password manager or use secret-tool to store it in the local keyring, e.g. with
secret-tool store --label="ruroco" token ruroco
ruroco-clientUsage: ruroco-client
Commands:
gen Generate a shared AES key (base64 with embedded key id)
send Send a command to a specific address
update Update the client binary
wizard Run the wizard to set up the server side
reseed Reseed the replay-protection counter to the current timestamp
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
ruroco-client genGenerate a shared AES key (base64 with embedded key id)
Usage: ruroco-client gen
Options:
-h, --help Print helpruroco-client send --help…Pass the path to a file holding the same base64 key string that you placed on the server (never
the key itself on the command line: that would leak it via ps and shell history). Example:
secret-tool lookup token ruroco > /run/user/$(id -u)/ruroco.key
ruroco-client send -a 127.0.0.1:80 -k /run/user/$(id -u)/ruroco.key -c defaultruroco-client update --helpUpdate the client binary
Usage: ruroco-client update [OPTIONS]
Options:
-f, --force Force update even if already on the latest version
-v, --version Target version to install (default: latest)
-b, --bin-path Directory where the binary is saved (default: same as current binary)
-s, --server Update server-side binaries instead of the client
-h, --help Print helpEvery downloaded binary is verified against an Ed25519 signature before it is written to
disk. The public key is embedded in the client at build time; releases are signed in CI with
the matching private key. If the .sig asset is missing or the signature does not match, the
update aborts and the existing binary is left untouched. As a result, the client can only
update to releases that ship signatures (v0.14.0 and later).
ruroco-client reseedResets the local replay-protection counter to the current nanosecond timestamp. Use this if the counter file is lost or corrupted, or after a system clock jump that would cause the server to reject packets.
The UI equivalent is the Reseed Counter button on the dashboard.
ruroco-client wizard --helpRun the wizard to set up the server side
Usage: ruroco-client wizard [OPTIONS]
Options:
-f, --force Overwrite existing configuration files
-h, --help Print helpruroco-server --helpUsage: ruroco-server [OPTIONS]
Options:
-c, --config [default: /etc/ruroco/config.toml]
-h, --help Print help
-V, --version Print versionruroco-commander --helpUsage: ruroco-commander [OPTIONS]
Options:
-c, --config [default: /etc/ruroco/config.toml]
-h, --help Print help
-V, --version Print versionruroco-client gen > ~/.config/ruroco/user.key to create a shared base64 key (includes key id).key file to the server config dir (default /etc/ruroco/user.key); the server loads every *.key
file there. It must be readable by the user the server runs as, so install it root:ruroco with mode 0640
(chown root:ruroco /etc/ruroco/user.key && chmod 640 /etc/ruroco/user.key). Leaving it root:root 0600 makes
the server crash-loop on EACCES./etc/ruroco/config.toml -> see config.toml. Same ownership as the key
(root:ruroco, mode 0640): the commander reads it as root, the server as ruroco, and neither needs to write it/etc/ruroco/commands.toml -> see commands.toml. This file is read
only by the commander (root) and must be installed root-owned with mode 0600 so the unprivileged server process
cannot read the command set.ruroco-client send with -k ~/.config/ruroco/user.key so client and server share the identical keyruroco's core job is to trigger a pre-configured action on the server. The strongest cases are the ones where there is no service to connect to at all — only something to make happen. The SPA example below (opening a port on demand) is the one shape of use case that overlaps with what a VPN can do; for why ruroco is still a distinct tool, see ruroco vs WireGuard / VPN.
The most VPN-orthogonal use of ruroco is firing a server-side action that has no "service" to reach: deploy, restart something, rotate a secret, run a backup. Configure the commands on the server:
# /etc/ruroco/commands.toml (root-only, see chapter "server config")
[commands]
deploy = "/usr/local/bin/deploy.sh"
restart_app = "systemctl restart myapp"
run_backup = "/usr/local/bin/run-backup.sh"then fire one from anywhere — including a CI runner, a cron job on another host, or a tap in the UI:
ruroco-client send --address host.domain:80 --command deploy --key-file ~/.config/ruroco/user.keyThere is no tunnel to bring up and no session to maintain: the client sends a single stateless packet and the command runs. A VPN cannot do this — it would only connect you so that you could then run the command yourself. And because the client can only pick from whitelisted command names (it never sees the command strings), a compromised client can fire those actions but gains no foothold on your network.
Any port you expose to the internet attracts brute-force and exploit traffic — and even a well-secured service is not 100% safe, see https://www.schneier.com/blog/archives/2024/04/xz-utils-backdoor.html or https://www.qualys.com/2024/07/01/cve-2024-6387/regresshion.txt
Blocking every port that does not need to be open at all times reduces that attack surface. But blocking a port completely makes the service behind it unreachable when you actually do need it.
This is where ruroco comes in: it can open a firewalled port for just a short while — only for the IP that
asked — and close it again afterwards. A command can reference that IP via the $RUROCO_IP environment
variable, which the commander substitutes before running the command:
# /etc/ruroco/commands.toml (root-only, see chapter "server config")
[commands]
open_port = "ufw allow from $RUROCO_IP proto tcp to any port 8443" # open the service for the requesting IP
closNo open issues yet, or sync has not completed.