Client setup

Clients turn BibaVPN into a local SOCKS5 (and optional HTTP CONNECT) proxy. You can use the GUI (Releases), the bibavpn-client CLI, or the Docker Hub client image.

Prerequisites

  • You must know host:port, --sni, token, and psk (or a biba:// invite + passphrase).
  • TLS trust: Prefer a public CA cert, --pin-cert leaf.pem (rustls or boring with boring-tls build), or embedded pin inside a v3 invite. --insecure is lab-only—it disables certificate verification.

Graphical apps (Android and desktop)

  1. Open GitHub Releases.
  2. Download the APK or desktop package for your OS from the same version as your server.
  3. Install per platform norms (Android: allow “install unknown apps”; desktop: follow bundle instructions).
  4. Paste either: - Invite URI + passphrase, or - Manual server parameters if the UI exposes them.

The GUI wraps the same Rust core as bibavpn-client. If something fails, compare versions and secrets first.

CLI: connect with explicit flags

Example matching a server at vpn.example.com:8443:

./bibavpn-client \
  --server "vpn.example.com:8443" \
  --sni "vpn.example.com" \
  --token "$BIBA_VPN_TOKEN" \
  --psk "$BIBA_VPN_PSK" \
  --decoy-max 24 \
  --max-pad 64 \
  --max-ws-binary 262144 \
  --ws-ping-secs 25 \
  --socks5 127.0.0.1:1080

Optional HTTP CONNECT proxy on another port:

  --http-proxy 127.0.0.1:8080

Self-signed / private CA server (testing only):

  --insecure

Leaf pin (no insecure flag):

  --pin-cert /path/to/server-leaf.pem

Shaping flags (--decoy-max, --max-pad, --max-ws-binary, WS ping, jitter, parallelism, etc.) should be aligned between client and server for predictable behavior. Start from the examples in README.md and tune using AGENTS.md.

CLI: connect from an encrypted invite

--from-invite is mutually exclusive with --server / --token (the invite carries them).

./bibavpn-client \
  --from-invite 'biba://…' \
  --invite-passphrase "$BIBA_INVITE_PASSPHRASE" \
  --socks5 127.0.0.1:1080

See Encrypted invite in PROTOCOL.md.

Docker client (Hub image)

docker-compose.hub.yml runs bibavpn-client beside biba-server and publishes:

Host Service
127.0.0.1:11080 SOCKS5
127.0.0.1:11880 HTTP CONNECT

Smoke test from the host:

curl --socks5-hostname 127.0.0.1:11080 https://ifconfig.io
curl -x http://127.0.0.1:11880 https://ifconfig.io

The Hub compose example sets --insecure because it uses an internal self-signed cert—only for that pattern.

Point applications at the proxy

Once bibavpn-client listens on 127.0.0.1:1080 (or your chosen port):

Firefox

Settings → Network Settings → Manual proxy → SOCKS Host 127.0.0.1, Port 1080, SOCKS v5 → enable Proxy DNS when using SOCKS v5.

Chrome / Chromium

Launch with:

--proxy-server="socks5://127.0.0.1:1080"

curl

curl --socks5-hostname 127.0.0.1:1080 https://example.com/

Environment variable (many CLI tools)

export ALL_PROXY=socks5h://127.0.0.1:1080

Linux: proxychains

Install proxychains-ng (distribution-specific) and configure it to point at 127.0.0.1:1080.

Protocol version and domain

  • Wire format is Biba v3 by default (--proto 3).
  • --proto-domain on the client must match the server’s --proto-domain, unless you rely on the documented default/SNI interaction—when unsure, set both explicitly to the same string.

Troubleshooting (short)

Symptom Things to check
TLS errors Certificate name vs --sni, expired cert, wrong chain, or need --pin-cert
Auth / handshake failures token / psk mismatch, wrong --proto-domain, mixed binary versions
Works for TCP but not UDP UDP mux uses a separate WebSocket; firewall or MTU issues on path
“Works in curl, not in browser” DNS leak—use socks5h / Firefox “Proxy DNS”

Deep detail: AGENTS.md and PROTOCOL.md.

Security reminders

  • Never paste psk, token, or invite passphrases into public tickets or logs.
  • --insecure hides active MITM—use only on trusted loopback labs.
  • The server operator is in a full MITM position for your proxied traffic by design.

Related