Colitu on Raspberry Pi and headless Linux

The headless client runs Colitu on machines without a screen or desktop: a Raspberry Pi, a mini PC or a Linux server. It has two parts: colitud, a system service that keeps your sign-in and runs the VPN tunnel, and colitu, a command you use in the terminal to sign in, pick a server and connect. The headless client is new and still in beta.

#Requirements

• A 64-bit system: Raspberry Pi OS (64-bit) based on Debian 12 "Bookworm", or Debian or Ubuntu on x64 or ARM64. A Raspberry Pi 3, 4, 5 or Zero 2 W works; the older 32-bit-only models (Pi 1, Pi 2, Pi Zero W) do not. Check with uname -m: it must say aarch64 (Raspberry Pi) or x86_64.
• systemd (every current Raspberry Pi OS has it) and an internet connection.
• A Colitu account with an active plan. The Pi counts as one of your devices.
• Another device with a browser (phone or computer) to approve the sign-in. You never type your password on the Pi.

#Install

1. On the Pi, download the ARM64 .deb package from colitu.com/download/linux (on an x64 machine take the x64 one).
2. Install it from the download folder:

``` sudo apt install ./colitu-vpn_*_arm64.deb ```

The same package contains the desktop app and the headless client. On Raspberry Pi OS Lite there is no desktop, so the app is simply unused; it only takes some disk space. If you do have a desktop, both can be installed together, but connect with only one of them at a time.

1. The service is not started automatically. Start it and let it run at every boot:

``` sudo systemctl enable --now colitud ```

1. Allow your user to control it. Members of the colitu group can use the colitu command without sudo:

``` sudo usermod -aG colitu $USER ```

Log out and in again (or run newgrp colitu) for the group to take effect.

#Sign in

``` colitu login ```

The command shows a link, an 8-character code and (in a terminal) a QR code. On your phone or computer open the link, check that the code and the device name (<hostname> (headless)) match and approve. The Pi signs itself in within a few seconds. The code is valid for about 10 minutes; if it expires, run colitu login again. Sign-in tokens are kept in /var/lib/colitu/state.json, readable only by root.

#Connect, check, disconnect

To check that it works, note your public address before connecting (curl -s https://ifconfig.me) and run the command again afterwards: it should show a Colitu server's address. If the Pi has a browser, the VPN connection test also shows leaks.

#Start automatically at boot

``` colitu connect --country tr colitu autoconnect on ```

Connect once to the server you want, then switch autoconnect on. From then on colitud connects to that last server whenever it starts, and keeps retrying until the network is up. colitu autoconnect off turns it off. The Pi's clock matters: it has no battery clock, and the connection only works once the time is synchronized. This normally happens a few seconds after the network comes up.

#Kill switch and your local network

While connected, all traffic of the Pi goes through the tunnel and cannot leave outside it (strict routing). Your local network stays reachable, so an SSH session into the Pi keeps working when you connect. This covers the private ranges 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and 169.254.0.0/16.

One consequence for DNS: programs on the Pi that use your router as their DNS server (the default on Raspberry Pi OS) still send those queries to the router directly, because the router is on the local network. To send them through the tunnel, give the Pi a public resolver, for example sudo nmcli connection modify "<connection name>" ipv4.ignore-auto-dns yes ipv4.dns 1.1.1.1 and reconnect the network. Queries to a public resolver are caught by Colitu and answered privately through the tunnel.

Be aware of what this is not: the headless client has no firewall-based kill switch like the desktop app. If the tunnel process dies, colitud restarts it automatically, but until the tunnel is back the Pi's traffic can go out directly. The same applies to the first seconds after boot, before autoconnect has connected. Using the Pi as a gateway that shares the VPN with other devices is not supported.

#Logs

``` journalctl -u colitud -f ```

shows what the service is doing (sign-in, connection attempts, reconnects). Tokens and server credentials are never written to the log.

#Update and remove

• Update: install the new .deb the same way. A running colitud is restarted by the package and reconnects if autoconnect is on. Your sign-in is kept.
• Remove: sudo apt remove colitu-vpn stops the service and takes the tunnel down. sudo apt purge colitu-vpn also deletes the saved sign-in. Run colitu logout --remove-device first if you want the Pi to disappear from your account's device list as well; you can also remove it on colitu.com under Devices.

#Troubleshooting

• colitud is not running: run sudo systemctl enable --now colitud, then systemctl status colitud. If it fails, journalctl -u colitud -e says why.
• no permission to use the colitud socket: your user is not in the colitu group yet. Run sudo usermod -aG colitu $USER and log in again.
• The sign-in code expired or was declined: run colitu login again and approve it from a device that is signed in to your account.
• This device is paused: your plan allows fewer devices than are signed in. colitu activate makes the Pi the active device and pauses the least recently used one. See Device management.
• no active plan or verify your e-mail address: fix it in your account at colitu.com, then run colitu connect again.
• It does not connect: check the date with timedatectl (it must say System clock synchronized: yes; the secure connection fails with a wrong clock), then read journalctl -u colitud -e. See also Connection problems.
• sing-box was not found: the package is incomplete; reinstall it. The tunnel core is installed at /opt/colitu-vpn/bin/sing_box/sing-box.
• Another VPN is running on the Pi (WireGuard, Tailscale exit node, the desktop Colitu app): two VPNs should not run at the same time. Disconnect the other one first.