Getting started

rustle is a single binary. This page takes you from nothing to a request going through your own proxy.

Install

curl -fsSL https://raw.githubusercontent.com/EdouardCourty/rustle/main/install.sh | sh

The installer detects your system, downloads the release for it, checks its SHA-256 and runs rustle --version before installing. It never uses sudo: it installs into /usr/local/bin when run as root and into ~/.local/bin otherwise, and tells you if that folder is not in your PATH. Linux (x86_64 and aarch64, glibc 2.35 or newer) and macOS (Apple Silicon and Intel) are supported.

To install a given version, set the variable on the sh side of the pipe:

curl -fsSL https://raw.githubusercontent.com/EdouardCourty/rustle/main/install.sh | RUSTLE_VERSION=v1.0.0 sh

Create a config

rustle init

This writes ~/.config/rustle/config.toml (or $XDG_CONFIG_HOME/rustle/config.toml when that variable is set), readable by you only, with a freshly generated API key. The key is printed once; it is also in the file.

The generated file listens on 0.0.0.0:8080, that is on every network interface, and that port sends the key in clear text. To try rustle on your own machine, restrict it to the loopback interface:

[server]
listen = "127.0.0.1:8080"

Then check the file without starting anything:

rustle check

check validates the syntax, rejects unknown keys and loads the certificate if you configured one. It warns when api_keys is empty, because then anyone who can reach the port can use your proxy.

Run it

rustle run

rustle runs in the foreground until you stop it with Ctrl+C; open connections get a few seconds to finish. Without arguments, rustle looks for ./config.toml, then ~/.config/rustle/config.toml, then /etc/rustle/config.toml, and uses the first one that exists. Pass a path to use another file: rustle run /path/to/config.toml.

Send a request through it

The API key is the proxy password. The user name is ignored: use anything, or leave it empty.

curl -x http://me:YOUR_KEY@127.0.0.1:8080 https://example.com

curl sends https:// URLs through a CONNECT tunnel, so this works for HTTP and HTTPS sites alike. Other ways in, each on its own port, are off until you set their address in the config:

• HTTPS to the proxy (the key is then encrypted on the way to the proxy), with [tls] listen. See Security.

  curl --proxy https://proxy.example.com:8443 -U me:YOUR_KEY https://example.com
  

  Add --proxy-http2 (curl 8.1 or newer) to speak HTTP/2 to the proxy.
• SOCKS5, with [socks5] listen. Use socks5h so that rustle resolves the host name:

  curl -x socks5h://me:YOUR_KEY@127.0.0.1:1080 https://example.com
  

A key with /, + or = in it (the output of openssl rand -base64 32, for instance) breaks a URL such as http://me:KEY@host. Pass the credentials separately with -U me:KEY, or percent-encode the key. The keys written by rustle init are hexadecimal and need no care.

Keep it running

rustle service enable

On Linux this installs a systemd user unit and starts it. It stops when you log out unless you run sudo loginctl enable-linger $USER once. On macOS it installs a launchd agent that starts at login, and writes its log to ~/Library/Logs/rustle.log.

For a system-wide service on Linux, create the config where the unit will read it first, then enable it:

sudo rustle init --path /etc/rustle/config.toml
sudo rustle service enable --system

The system unit runs as a dedicated rustle user, which service enable --system creates if it is missing. Manage either kind with rustle service status, restart, stop or logs; see Commands.

Where next

• Configuration: every setting, its default, and whether a reload applies it.
• Security: rotate keys, encrypt the connection, limit who connects and where they can go.
• Commands: what each rustle command does.