All docs sections
You rent a small server, enter its IP and password in Routekeeper, and get your own proxy. One command in Terminal on the server gives the same result. Routekeeper sends the traffic of the apps you choose to this server, and the server passes that traffic on to the internet.
App → Routekeeper → TLS → your server :443 → internet
An HTTPS proxy: HTTP CONNECT inside TLS on the Caddy web server with the forwardproxy@naive build. You don’t need to install anything on your Mac except Routekeeper.
Without the password, the server answers like an ordinary web server with a Let’s Encrypt certificate. So scanners don’t find an open proxy, and strangers can’t use it.
The password is created on the server itself. Neither the password nor your traffic is sent to Routekeeper or its author. Where the script connects during installation is listed below.
This kind of proxy carries only TCP. By default, Routekeeper blocks UDP from apps that go through it, and browsers switch to TCP. See Limitations for details.
What you need
- A server. A rented VPS with Debian or Ubuntu. What exactly to order is described below.
- A domain. Your own, or a free one from DuckDNS: Let’s Encrypt issues the certificate for it. How to get one is in step 1.
- A Mac with Routekeeper. If Routekeeper isn’t installed yet, start with the Quick start. Terminal is needed only for setting it up by hand, and macOS already has it.
- About 15 minutes. The installation on the server itself takes 1–3 minutes.
Which server to order
A VPS is a virtual server that a hosting provider rents out by the month. The cheapest plan will do. When you order, choose:
- Operating system: Debian 12 or 13, Ubuntu 22.04 or 24.04. The script has been tested on these.
- CPU: x86_64, also called amd64, x64 or Intel/AMD. ARM servers (arm64, aarch64) won’t work: there is no ready Caddy build with the proxy for them.
- Memory: 1 GB or more. Disk: the smallest one offered.
- Address: a public IPv4. A plan with IPv6 only won’t work.
- Region: the one closest to you. Each new connection through the proxy takes about three pings to the server to set up, so the closer the server, the faster everything opens.
- Virtualization, if the provider lists it: KVM is better. The proxy also works on container-based VPS (OpenVZ, LXC), but the BBR speed-up isn’t available there.
The server needs free ports 80 and 443. If the server already runs a website, another VPN panel or a web server, the script won’t touch anything and will stop. Use a separate server for the proxy.
Where to find the IP and password
After you pay, the hosting provider sends you an email with the server’s IP address and the password of the root user, the server’s main administrator. The same details are usually on the server’s page in the provider’s control panel. If you can set the root password yourself when you order, make it long and random.
Some providers, more often cloud ones, give you a regular user instead of root (for example, ubuntu). This user can run administrator commands with sudo. That works too: every step has commands for this case.
If the provider asks for an SSH key when you order, create a key on your Mac as in the first step of Protecting the server, and paste its public part into the form. You can copy it with pbcopy < ~/.ssh/my_server.pub. Then log in to the server with the key: ssh -i ~/.ssh/my_server root@IP.
Setting it up from Routekeeper
Routekeeper logs in to the server over SSH itself, runs the same installation script as the Terminal command, and adds the finished proxy to the list. Open the wizard in one of these ways:
- the Proxy section → the Add Proxy button’s menu in the toolbar → Your Own Server…;
- an empty proxy list → Your Own Server… under Add a proxy;
- the welcome screen → the Add a proxy server step → Your Own Server….
- Server. Enter the server’s IP address and the root password from the hosting provider’s email, and click Connect. If you log in to the server with an SSH key, choose SSH key and pick the key file. A user other than root who may use
sudowithout a password, and a non-standard port, are set under User and port.Routekeeper creates its own key for the server, adds the public part to the user’s
~/.ssh/authorized_keyson the server, and checks that logging in with the key works. From then on Routekeeper logs in only with the key and forgets the password. Then it checks the server without changing anything: the system, the processor, free ports 80 and 443. - Domain. Routekeeper shows the system, the public IP and the fingerprint of the server’s key. Choose a domain:
- A free one on DuckDNS. Create a name on duckdns.org as in step 1 and enter it. If you also enter the DuckDNS token (it’s at the top of the same page), Routekeeper points the name at the server’s IP itself, and you don’t need to change
current ipon the site. The token isn’t saved. - My own domain. Create an A record with the server’s IP as in Your own domain, and enter the name.
- A free one on DuckDNS. Create a name on duckdns.org as in step 1 and enter it. If you also enter the DuckDNS token (it’s at the top of the same page), Routekeeper points the name at the server’s IP itself, and you don’t need to change
- Install. The wizard shows the script’s stages as they run. The installation usually takes 1–3 minutes.
- Done. The proxy is already added to Routekeeper, named after the domain, and checked. If you want, turn on Turn off password logins to the server (see below) and click Done. Then choose the apps that will go through the proxy.
- The IP address from the hosting provider’s email. The server’s host name works too.
- Log in with the root password, or with the SSH key you already use for the server (Choose Key… opens the
~/.sshfolder). - This is where you change the SSH user and port. A user other than root works if
sudolets it in without a password. - The fingerprint of the server’s key. Routekeeper remembers the key on the first login and refuses to connect if a different server answers at this address.
- Your own domain: Routekeeper shows which A record to create.
- With a DuckDNS token, Routekeeper points the name at the server’s IP itself. Without one, do it on the DuckDNS site. The token isn’t saved.
- The installation stages are the same ones the script prints in Terminal. If a stage fails, it turns red, and below it appear the message, Details and a What to do about it link.
- Stop interrupts the installation. The server stays as far as the script got. Running the installation again is safe: it finishes the rest. After an error, the buttons here are Back and Try Again.
- The proxy is already added to Routekeeper and checked: you see the check time and the IP address websites will see.
- Off by default. If you turn it on, after Done the server stops accepting passwords and lets in only keys.
If a step fails, the wizard shows the message, Details under it, and a What to do about it link to the right part of If something goes wrong. The messages are the same ones the script prints. Fix the cause and click Try Again: the script skips what’s already done.
If a Routekeeper proxy is already installed on the server, the wizard says so on the Domain step and fills in the domain. The button then says Update: the login and password are kept, and the proxy with this domain in Routekeeper is updated rather than added a second time.
Password logins to the server
Bots try to guess SSH passwords around the clock. fail2ban blocks an address after five failures, but it’s safer to turn off password logins completely. The Turn off password logins to the server switch on the last step does this: Routekeeper creates /etc/ssh/sshd_config.d/10-routekeeper-keys-only.conf and reloads the SSH settings. If sshd -t finds an error in the settings, the file is removed and nothing changes. The switch is off by default. You can do the same later in the proxy card.
After that, the server lets in only keys. To log in yourself from Terminal, save Routekeeper’s key: in the proxy card, More → Save SSH Key…, then ssh -i ~/.ssh/file root@IP. Programs that log in to the server with the root password (VPN panels, for example) will need a key too. If you lose access, log in through the server’s web console in the hosting provider’s panel and delete this file.
Managing the server
A proxy set up by the wizard has a Server block in its card in the Proxy section: whether the proxy is running on the server, when the certificate expires, how many addresses fail2ban is blocking. It also has buttons to update the server, change the proxy password, turn off password logins, save the SSH key and remove the proxy from the server. See Proxies for details.
More: what Routekeeper keeps and what it does on the server
- Routekeeper’s key is ed25519, one per server. The private part is in the macOS keychain (service
app.getroutekeeper.mac.server-key), the public part inauthorized_keyson the server, labelledroutekeeper@IP. - Routekeeper keeps the server’s address, user, port and domain in
~/Library/Application Support/app.getroutekeeper.mac/servers.json, and the server key it saw on the first login next to it, in theserversfolder. The server password and the DuckDNS token aren’t saved. - The installation script is built into the app: it’s the same
server.shthe site has for this version of Routekeeper. The wizard hands it to the server over SSH; the server doesn’t download anything from the Routekeeper site. - The proxy’s login and password are created on the server and go to Routekeeper’s network extension, as when you paste a proxy string. The Routekeeper window doesn’t keep them.
- Routekeeper runs the system
/usr/bin/sshwithout your settings from~/.ssh/configand without ssh-agent. - Removing the proxy from the server and Forget Server… don’t remove Routekeeper’s key from
authorized_keys: with password logins off, it may be the only one. You can remove it by hand — it’s the line ending inroutekeeper@IP.
Backup route
Sometimes a server is fine but your Mac can’t reach it: the provider blocked the address or a route broke. If you have a second server with a Server block, connections can reach the first one through it. Sites keep seeing the first proxy’s address.
- Open the card of the proxy that needs a backup route.
- In Route to the Proxy, pick the second server in Backup route and confirm.
Routekeeper tries the main route first. If there’s no answer within five seconds, the connection goes through the second server, and every 30 seconds Routekeeper checks whether the direct route is back. The card shows the route in use.
To send connections through the second server all the time, turn on Always Through This Server. The first proxy is then never used directly, and if the second server is unreachable, connections won’t open.
A backup route only works for an HTTPS proxy with a login and password. The first proxy’s login and password are kept on the second server, and while connections go through it, that server sees the domains you visit. If the first server itself is off, the backup route won’t help: there’s nothing left to exit from at its address.
If Routekeeper reports a setup error, check that both proxies work on their own. not_installed and needs_update mean the second server has no proxy or runs an old version: update it in its card. chain_check_failed means the second server couldn’t get out through the first, for example because the first is unreachable from there too or its password changed. bad_upstream and chain_not_found are internal errors: a wrong address of the first proxy, or an entry that’s no longer on the server. Turn the backup route off and on again.
Setting it up by hand
If you’d rather do everything yourself, or set up the proxy from another computer, follow the four steps below: the domain, logging in to the server, the install command and adding the proxy to Routekeeper.
1Domain
The proxy needs a domain name. Let’s Encrypt issues the certificate for this name, and Routekeeper uses the certificate to make sure it is connecting to your server. The name is linked to the server by an A record: a line in DNS of the form “name → IPv4 address”.
A free domain on DuckDNS
- Sign in at duckdns.org with GitHub, Google or another option they offer.
- In the
sub domainfield, type a name: letters a–z, digits and hyphens. Clickadd domain. You get an address likename.duckdns.org. - DuckDNS puts your computer’s address into the
current ipfield right away. Replace it with the server’s IP and clickupdate ip.
When you set things up by hand, you won’t need the DuckDNS token: the server’s IP doesn’t change, so the record never needs updating. The Routekeeper wizard doesn’t need it either, but with it Routekeeper does the third step itself.
Your own domain
In your registrar’s or DNS host’s panel, create an A record. The name is a subdomain (or @ for the domain itself), and the value is the server’s IP. If Cloudflare serves the domain, turn off proxying for the record (gray cloud, “DNS only”). Otherwise the domain will point to Cloudflare’s addresses, not to your server.
If the domain has an AAAA record (IPv6) that points to a different address, delete it. Let’s Encrypt may check the domain over IPv6, and then it won’t issue the certificate.
Check the record
The record starts working in a couple of minutes. Check it on your Mac: the command should print the server’s IP.
dig +short name.duckdns.org2Logging in to the server
You log in to the server over SSH from Terminal. To open Terminal, go to Applications → Utilities → Terminal, or press ⌘Space and type “Terminal”. Connect, using the IP from the provider’s email:
ssh root@IPIf the provider gave you a user with sudo instead of root, use that user’s name:
ssh user@IPThe first time you connect, ssh asks: Are you sure you want to continue connecting (yes/no/[fingerprint])? This means ssh sees this server for the first time. It also shows the fingerprint of the server’s key. Type yes and press Return. ssh will remember the server’s key and warn you if a different server ever answers at this address.
Then enter the password. The characters don’t appear as you type, and that’s normal. You can paste the password with ⌘V. You’re in when the line in Terminal changes to something like root@server-name:~#.
Some providers ask you to change the password the first time you log in. Enter the current password, then the new one twice.
3Installation
On the server, run one command with your domain in it:
curl -fsSL https://getroutekeeper.app/server.sh | bash -s -- --domain name.duckdns.orgIf you logged in as a user with sudo rather than as root, add sudo before bash. sudo may ask for that user’s password.
curl -fsSL https://getroutekeeper.app/server.sh | sudo bash -s -- --domain name.duckdns.orgInstallation usually takes 1–3 minutes. The script does the following, in this order:
- checks that the server runs Debian or Ubuntu on x86_64 with systemd, and installs any missing standard packages;
- checks that the domain points to this server and that ports 80 and 443 are free; if the ufw firewall is on, opens these ports in it;
- downloads Caddy with the forwardproxy@naive build and verifies its checksum;
- creates a login and a long random password;
- sets up Caddy: a proxy with a password, and a simple web page for anyone who comes without the password; Caddy gets and renews the Let’s Encrypt certificate by itself;
- turns on BBR, an algorithm that controls TCP speed and noticeably speeds up connections over long distances;
- installs fail2ban: after five failed SSH logins within an hour, an address can’t reach the server for a day, and longer if it keeps trying;
- turns on automatic security updates; the server doesn’t reboot by itself;
- checks that the proxy works with the password and that without the password the server answers like an ordinary web server, then prints the line for Routekeeper.
BBR, fail2ban and updates are optional. If the server doesn’t allow them, the script prints a warning and goes on installing the proxy.
What you’ll see
This is the output of a successful installation. Your domain, IP and login will be different, and instead of ••• you’ll see a 40-character password.
OS: Debian GNU/Linux 12 (bookworm) (x86_64)
==> Checking the domain my-name.duckdns.org
server: 203.0.113.10, my-name.duckdns.org → 203.0.113.10
==> Caddy v2.11.2-naive
Caddy restarted
==> BBR
TCP: bbr
==> fail2ban for SSH
5 failed logins in an hour → banned for a day, longer for repeat offenders
==> Automatic security updates
on, the server never reboots by itself
==> Checks
✓ Let's Encrypt certificate obtained, the site is up
✓ proxy works with the password, exit IP 203.0.113.10
✓ without the password the proxy is closed to strangers
Done. Copy the line and paste it into Routekeeper: Proxy → ⌘V (or the Paste Link button) → Add.
https://u3f9a1c0b7e42:•••@my-name.duckdns.org:443
Or fill it in by hand: type HTTPS, server my-name.duckdns.org, port 443, login u3f9a1c0b7e42, password •••.
The line is the key to your proxy: keep it private. To see it again: cat /etc/caddy/proxy-credentials
Lines with ==> are stages, and lines with ✓ are checks that passed. If ufw is on, the line ufw: opened ports 80 and 443 appears after the domain check. At the “Checks” stage, the script may print nothing for a few minutes while Caddy gets the certificate.
Lines with ! are warnings. The installation goes on, and at the end, before “Done”, the warnings are repeated. A line with ✗ is an error, and the script stops after it. What to do about each one is in If something goes wrong.
Read the script before running it
It’s wise to read a script from the internet before you run it. The source is open: view the script on GitHub. To run exactly the file you read, download it to the server:
curl -fsSLO https://getroutekeeper.app/server.shLook through it. Press Space to scroll and q to quit.
less server.shThen run it (as a sudo user: sudo bash server.sh …):
bash server.sh --domain name.duckdns.orgWhere the script connects
- api.ipify.org, or ifconfig.me if that doesn’t answer, to find the server’s public IPv4. At the end, the script uses the same services to check the proxy itself.
- GitHub, to download the Caddy build from the releases of the klzgrad/forwardproxy project. Its SHA-256 checksum is written in the script. If the downloaded file doesn’t match it, the installation stops.
- Debian or Ubuntu package mirrors set up on the server, to install standard packages: curl, openssl, fail2ban, unattended-upgrades and others.
- Let’s Encrypt. Caddy gets the certificate for your domain from it and then renews it by itself.
The script itself is downloaded from getroutekeeper.app and doesn’t contact that site again. The login and password are created on the server and stored only there. Neither the password nor your traffic is sent to Routekeeper or its author.
After installation, the server on its own contacts only Let’s Encrypt, to renew the certificate, and the package mirrors, for security updates.
Flags and running it again
It’s safe to run the install command again. The login and password are kept. Caddy restarts only if its program or settings changed; otherwise the script prints “Caddy is already set up, no restart needed”. Add flags at the end of the command.
| Flag | What it does |
|---|---|
--domain name | The domain whose A record points to this server. Required for installation. |
--new-password | Creates a new login and password. The old ones stop working right away. |
--no-bbr | Doesn’t turn on BBR. TCP settings stay as they are. |
--no-fail2ban | Doesn’t install fail2ban. |
--no-auto-updates | Doesn’t turn on automatic security updates. |
--lang ru, --lang en | The language of the messages. By default, the script takes it from the LANG variable, and ssh usually passes the language from your Mac. Add --lang en if the messages come out in Russian. |
--json | For scripts and apps: the result is printed as one line of JSON. |
--uninstall | Removes the proxy. Use it instead of --domain. BBR, fail2ban and updates stay. |
The --no-… flags only skip a step. They don’t undo what an earlier run did.
Details: the --json flag
With --json, only one line of JSON goes to standard output. Progress messages and errors go to stderr. Fields: type (always https), host, port, username, password, url (the same line you get without the flag), serverIP, caddy (the version), and warnings, an array of warnings that is empty if there were none. On an error, no JSON is printed and the exit code is non-zero.
Details: what changes on the server
/usr/local/bin/caddy: Caddy v2.11.2 with the forwardproxy@naive build from the klzgrad/forwardproxy releases. The SHA-256 of the archive is written in the script./etc/caddy/Caddyfile: a site on :443 for your domain with TLS 1.2 and 1.3,forward_proxywithbasic_auth,hide_ip,hide_via,probe_resistanceandacl, andfile_serverwith the page from/var/www/site. Before the file is installed, the script checks it withcaddy validate./etc/caddy/proxy-credentials: the login and password, with permissions 600.- The systemd service
caddy, running as the system usercaddy. Caddy keeps its certificates in/var/lib/caddy. - BBR and the
fqqueue:/etc/sysctl.d/99-zz-bbr.confand/etc/modules-load.d/bbr.conf. The99-zzprefix keeps the provider’s settings from overriding them. - fail2ban:
/etc/fail2ban/jail.d/zz-routekeeper.localand/etc/fail2ban/fail2ban.d/zz-routekeeper.local. Bans use nftables. 5 failed logins in an hour mean a ban for a day; for repeat offenders the ban doubles each time, up to 4 weeks. The server itself and the address the script was run from are never banned (if you run the script through sudo, that address may be missing from this list). - Updates: the unattended-upgrades package and
/etc/apt/apt.conf.d/20auto-upgrades.
probe_resistance: when a request comes to the proxy without the password, Caddy answers like a web server, not with code 407 “Proxy Authentication Required”. hide_ip and hide_via: Caddy doesn’t add the Forwarded and Via headers to requests. acl: the proxy refuses service addresses, such as the provider’s metadata service (169.254.169.254). This doesn’t make the link safe to hand out: whoever has it gets your login and the whole proxy. A server set up earlier gets acl when you update it. The script runs the final checks on the server itself through 127.0.0.1, so they don’t depend on how the provider routes the server’s connections to itself.
4Adding it to Routekeeper
At the end, the script prints a line like https://u3f9a1c0b7e42:…@name.duckdns.org:443. It has everything Routekeeper needs: type, server, port, login and password.
- Copy the line. In Terminal, triple-click it to select the whole line, and press ⌘C.
- Paste it into Routekeeper.
- First launch, the welcome screen is open. At the Add a proxy server step, click Paste from Clipboard. This step becomes available after the three macOS permissions.
- You’re past the welcome screen. Open the Proxy section and press ⌘V or click the Paste Link button below the list.
- Click Check. After a couple of seconds, “Working · … ms · IP …” appears next to it, with your server’s IP. The number in milliseconds is the time it takes to set up a new connection. It’s usually about three times the ping to the server.
- DNS through proxy and Block UDP and QUIC are already on. Leave them on. Click Add.
- Choose the apps that will go through the proxy. On the welcome screen, the next step has a Choose Apps… button for this. Later, use the Apps section: click Add and choose apps from the list of installed ones. If you have only one proxy, new apps go through it right away. If you have several, click the route on the right side of the app’s row and choose this proxy. See Apps and services for details.
If pasting didn’t work, fill in the fields by hand from the “Or fill it in by hand” line in the script’s output. The Server field must contain the domain, not the IP: the certificate is checked against the domain. For more about the fields, see Proxies. To make sure your apps’ traffic really goes through the server, use the check on the server.
The line is the key to your proxy. Don’t publish it or send it in chats. To see it again, run the install command once more. The login and password are stored on the server in /etc/caddy/proxy-credentials.
Protecting the server
Bots try to guess SSH passwords around the clock: our test server got about 11,000 attempts a day. fail2ban blocks an address after five failures, but it’s safer to turn off password login completely and log in with a key.
If the Routekeeper wizard set up the proxy, the Turn off password logins to the server switch does this, see above. By hand:
- Create a key on your Mac. When asked for a passphrase, you can press Return twice (a key without a password) or set a password for the key.
ssh-keygen -t ed25519 -f ~/.ssh/my_server - Give the server the public part of the key. This is the last time you’ll need the root password.
ssh-copy-id -i ~/.ssh/my_server.pub root@IP - Log in with the key. If you weren’t asked for the root password, the key works.
ssh -i ~/.ssh/my_server root@IP - In the same session, turn off password login:
printf 'PasswordAuthentication no\nPermitRootLogin prohibit-password\n' > /etc/ssh/sshd_config.d/10-keys-only.conf systemctl reload ssh - Don’t close this session. Open a new Terminal window (⌘N) and log in again with the command from step 3.
If you log in as a sudo user, use that user’s name instead of root in steps 2 and 3, and in step 4 run:
printf 'PasswordAuthentication no\nPermitRootLogin prohibit-password\n' | sudo tee /etc/ssh/sshd_config.d/10-keys-only.conf
sudo systemctl reload sshDon’t close the session until you’ve checked key login in a new Terminal window. If other apps manage the server with the root password, they will also need a key after this. If you do lose access, log in through the server’s web console in the provider’s panel and delete the file /etc/ssh/sshd_config.d/10-keys-only.conf.
Details: why the file is called 10-keys-only
sshd reads the files in /etc/ssh/sshd_config.d/ in alphabetical order and, for each setting, uses the first value it finds. The number 10 puts our file before the files from the provider and cloud-init (for example, 50-cloud-init.conf with PasswordAuthentication yes). To check the value in effect, run sshd -T | grep passwordauthentication. It should print passwordauthentication no.
Maintenance
If the Routekeeper wizard set up the proxy, it’s easier to update the server, change the password and remove the proxy with the buttons in the proxy card, in the Server block. Below is the same by hand.
All commands run on the server. As a sudo user, add sudo at the start of each command, and in the install command, before bash.
| Task | What to do |
|---|---|
| Update Caddy and its settings | Run the install command again. The login and password are kept, and Caddy restarts only if something changed. |
| See the proxy line again | Run the install command again: the line is printed at the end. For the login and password only: cat /etc/caddy/proxy-credentials. |
| Change the password | Run the install command with --new-password. It creates a new login and password. Then, in Routekeeper, open this proxy in the Proxy section, enter the new login and password from the script’s output, and click Save. App routes stay on this proxy. |
| Change the domain | Point the new name’s A record to the server and run the install command with the new --domain. In Routekeeper, change the proxy’s Server field and click Save. |
| Status and log | systemctl status caddy, journalctl -u caddy -n 50 |
| Who fail2ban is blocking | fail2ban-client status sshd. To unban an address: fail2ban-client set sshd unbanip IP. |
| System updates | Security updates install by themselves. For the rest, run apt update && apt upgrade. If the file /var/run/reboot-required appears, reboot the server with reboot. Caddy starts by itself. |
| Remove the proxy | Run the install command with --uninstall instead of --domain, see below. |
Removal deletes Caddy, its settings and certificates, the web page, and the login and password. BBR, fail2ban and automatic updates stay: they’re useful without the proxy too.
curl -fsSL https://getroutekeeper.app/server.sh | bash -s -- --uninstallDetails: how to remove BBR
Delete /etc/sysctl.d/99-zz-bbr.conf and /etc/modules-load.d/bbr.conf and reboot the server. To turn off fail2ban, run systemctl disable --now fail2ban. To turn off automatic updates, delete /etc/apt/apt.conf.d/20auto-upgrades.
If something goes wrong
The Routekeeper wizard shows the same messages as the script, and its What to do about it link leads to the right section below. Messages about logging in to the server are under Logging in to the server.
When there is an error, the script prints a line with ✗ and stops. Fix the cause and run the same command again. The script skips what’s already done, and the login and password are kept. Below is every script message and what to do about it.
Starting the script
curl: command not found
The server has no curl to download the script. Install it and repeat the install command (as a sudo user, put sudo before each of the two commands):
apt-get update && apt-get install -y curlbash: --domain: invalid option
The two hyphens after bash -s are missing. It must be exactly bash -s -- --domain …. Copy the whole command from this page.
Usage: server.sh --domain NAME …
The script didn’t understand a flag. There may be a typo, no value after --domain or --lang, or a --lang value other than ru or en. Compare your command with the table of flags.
“Pass the domain: --domain my-name.duckdns.org”
The domain is missing or has a mistake. Write only the name, in Latin letters, without https:// and without a slash at the end: --domain name.duckdns.org.
“Run as root: … | sudo bash -s -- --domain name”
You logged in as a regular user. Add sudo before bash, as the hint shows.
“Debian or Ubuntu is required, this is OS name.”
The server runs a different system. Reinstall it in the provider’s panel and choose Debian 12 or 13, or Ubuntu 22.04 or 24.04. Reinstalling erases everything on the server.
“systemd is required.”
This happens on container-based VPS and in Docker containers. Choose a plan with KVM virtualization.
“An x86_64 (amd64) server is required: there is no ready Caddy proxy build for aarch64.”
The server runs on ARM. Order a plan with an x86_64 (amd64, Intel/AMD) CPU.
“Couldn't install: packages”
The standard packages the script needs didn’t install. Above this line is apt’s message with the reason. Common causes: the disk is full (df -h), the package mirrors can’t be reached, or the system is too old. Run apt-get update, fix what it complains about, and run the script again.
The script went quiet for a long time
On a fresh server, the system installs its own updates in the first few minutes, and the script waits up to 5 minutes for it to finish. You’ll most often see this after the line ==> fail2ban for SSH. At the ==> Checks stage, the script may wait a few minutes while Caddy gets the certificate. You don’t need to interrupt it.
Domain and ports
“Couldn't find the server's public IPv4. A server with a public IPv4 is required.”
The server has no public IPv4, or it can’t reach the internet. Check with curl -4 https://api.ipify.org: it should print the server’s IP. If your plan has IPv6 only, ask the provider for an IPv4 address or choose a different plan.
“The A record of name must point at IP. Fix it at your registrar or in DuckDNS and wait a couple of minutes.”
On the line above, the script shows where the domain points now: server: IP, name → address, or no record if there is no record at all.
- In DuckDNS, check the
current ipfield: it often still has your computer’s address. - If your own domain is on Cloudflare, turn off proxying for the record (“DNS only”).
- If you just changed the record, wait a couple of minutes and check it on your Mac with
dig +short.
“Ports 80 and 443 are taken by: programs. Looks like a web server or another VPN panel already runs here…”
The server already runs another VPN panel or a web server. The names of the programs come after the colon. The script doesn’t touch them. If you need them, use a separate server for the proxy.
If it’s a web server you don’t need that the provider installed with the system (for example, apache2), turn it off and run the script again:
systemctl disable --now apache2“This server already runs Caddy with its own sites (/etc/caddy/Caddyfile). The script won't touch it: use a separate server.”
Caddy on this server wasn’t installed by this script, and it serves other sites. The script doesn’t overwrite someone else’s settings. Use a separate server for the proxy. If you’re sure you don’t need this Caddy, remove it the same way it was installed, together with /etc/caddy/Caddyfile, and run the script again.
Caddy and the certificate
Stopped after ==> Caddy v2.11.2-naive with a curl: (…) error
The server couldn’t download Caddy from GitHub. This is usually a temporary problem with the network or with GitHub. Check with curl -I https://github.com and run the script again in a few minutes.
“Caddy checksum mismatch, stopping.”
The downloaded file is different from the one whose checksum is written in the script. It was damaged during the download or changed on the way. Caddy was not installed. Run the script again later. If the message repeats, don’t turn off the check. Instead, report the problem.
“The Caddy build lacks forward_proxy.”
/usr/local/bin/caddy already has Caddy of the same version, but it’s the standard build without the proxy, and the script didn’t replace it. If nothing else uses this Caddy, rename it and run the script again:
mv /usr/local/bin/caddy /usr/local/bin/caddy.old“Caddy rejected the configuration.”
Above this line is the reason from Caddy itself. This shouldn’t happen with a standard installation. Run the script again. If the message repeats, report the problem and include the output.
“Caddy didn't start, details: journalctl -u caddy -n 50”
Above this line are Caddy’s latest messages. journalctl -u caddy -n 50 shows the full log. Common causes:
address already in use: another service took port 80 or 443. Find it withss -tlnp.- The server ran out of memory or disk space. Check
free -manddf -h.
Fix the cause and run the script again.
“Caddy couldn't get a Let's Encrypt certificate. Usually ports 80 and 443 are closed in the hosting panel (firewall, security group)…”
The line above sometimes gives more detail: Let's Encrypt: reason.
- The ports are closed from outside. This is the most common cause, especially with
Timeout during connectin the detail. In the provider’s panel, find the firewall (firewall, security group, “network rules”) and allow incoming TCP on ports 80 and 443. Keep them open afterwards too: Caddy renews the certificate through them. - You just changed the domain. Let’s Encrypt still sees the old address or an old AAAA record (IPv6). Wait a few minutes. Delete any extra AAAA record.
- A Let’s Encrypt rate limit, with
rateLimitedortoo many certificatesin the detail. This happens if the proxy was installed and removed many times for the same name: removal deletes the certificate, and each installation asks for a new one. Wait (from an hour to a week, depending on the limit), or take a different name on DuckDNS and run the script with it.
Then run the script again.
Checks
“The proxy doesn't work with the password (got '…').”
The certificate was obtained, but a request through the proxy with the password didn’t return the server’s IP. The part in parentheses shows what came back instead.
- Nothing. The server couldn’t reach the internet through the proxy. Either the provider blocks outgoing connections, or api.ipify.org and ifconfig.me didn’t answer for a moment (the script tries both, three times). Run
curl -4 https://api.ipify.orgon the server and run the script again in a couple of minutes. - A different IP. The server has several public addresses, and it goes out from a different one than the domain points to. The proxy may still work. Add it to Routekeeper by hand (login and password:
cat /etc/caddy/proxy-credentials) and click Check.
“Without the password the proxy answers 407 instead of a plain web server response.”
The script checks that the server answers a request without the password like an ordinary web server. Here it answered with code 407 “Proxy Authentication Required”. That tells anyone it’s a proxy, so scanners can find it.
This shouldn’t happen with a standard installation. It usually means Caddy’s settings were changed by hand. Run the script again, and it will overwrite the settings. If the message repeats, report the problem.
Warnings
These lines start with !. The installation goes on after them, and the proxy works. At the end, before “Done”, they are repeated. With the --json flag, they go into the warnings field.
“BBR isn't available on this server (common on container-based VPS). The proxy works without it.”
On container-based VPS (OpenVZ, LXC), the server shares its kernel with the host, and its TCP settings can’t be changed. You don’t need to do anything.
Over long distances, a single connection without BBR can be noticeably slower: with a ping of about 200 ms, roughly 0.5 MB/s instead of 3. If speed matters, choose a KVM VPS. To stop the script from trying to turn on BBR, use the --no-bbr flag.
“fail2ban didn't install, SSH is left without password-guessing protection.”
apt couldn’t install fail2ban. Its message is above the warning. This doesn’t affect the proxy. Run the script again later, or simply turn off password login: then there’s nothing to guess.
“fail2ban rejected the configuration, SSH is left without password-guessing protection.”
The installed version of fail2ban didn’t accept the script’s settings. The script removed its files so that fail2ban can still start. fail2ban-client -t shows the reason. A reliable alternative is key-only login.
“fail2ban didn't start the SSH jail (journalctl -u fail2ban shows why).”
fail2ban is installed but didn’t turn on SSH protection. This happens on container-based VPS, where fail2ban can’t manage the firewall. Look at journalctl -u fail2ban -n 50. A reliable alternative is key-only login.
“unattended-upgrades didn't install, security updates have to be applied by hand.”
Automatic updates didn’t turn on. Run the script again later, or install updates yourself from time to time: apt update && apt upgrade.
Removal
“Run as root.”
You logged in as a regular user. Add sudo before bash: … | sudo bash -s -- --uninstall.
“Caddy on this server wasn't set up by Routekeeper, the script won't remove it.”
Caddy’s settings have no Routekeeper proxy: this is someone else’s Caddy with its own sites. The script doesn’t remove it. If you don’t need it, remove it the same way it was installed.
Logging in to the server
Messages from the Routekeeper wizard about logging in to the server:
| Message | What to do |
|---|---|
| The server didn’t accept the user name, password or key | As with Permission denied below: check the password and user in the hosting provider’s email. |
| The server’s key has changed since the last login | As with REMOTE HOST IDENTIFICATION HAS CHANGED below. If the system on the server was reinstalled, the proxy is gone too: run the wizard again, and the proxy in Routekeeper will be updated. |
| The server refused the SSH connection, The server doesn’t answer, The server can’t be reached from your network | As with Connection refused below. |
| There’s no such address | The IP field has a typo, or the server’s name isn’t found in DNS. |
| sudo asks “…” for a password | Log in as root, or let this user use sudo without a password. The wizard doesn’t support sudo with a password yet. |
| The key for this server isn’t in the keychain | Routekeeper’s key was deleted from the keychain. Run the wizard again with the password or your own key. |
ssh messages in Terminal:
WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
The server’s key has changed. This is expected after you reinstall the system on the server. Remove the old key on your Mac and connect again:
ssh-keygen -R IPIf you didn’t reinstall the system, don’t go on. Ask the provider what happened.
Permission denied
The password or user name is wrong. Check them in the provider’s email. If the provider doesn’t let root log in with a password, log in as the user the provider gave you and use sudo.
Connection refused or Operation timed out
The server is still starting up, the IP has a typo, or fail2ban is blocking your address after several wrong passwords. In the last case, wait a day, or log in through the web console in the provider’s panel and remove the ban: fail2ban-client set sshd unbanip your IP.
In Routekeeper
Check shows an error
The Server field must contain the domain, not the IP, and the whole line must be pasted. What each check message means is explained in Troubleshooting.
It’s slow
Choose a server closer to you. With BBR and a ping of about 200 ms, a single connection gets roughly 3–4 MB/s.
The proxy is unstable on your network
You can install a different proxy on the same server and connect to it through a local SOCKS5 client, such as sing-box or Xray. How to connect such a client to Routekeeper is described in Proxies.
If you’re stuck, open an issue on GitHub and attach the script’s output. Remove the proxy line and the password from it first.
Checked against the Routekeeper code (version 0.2.1 and the one after it) on October 4, 2026.