DocsWireGuard mode

Capture

WireGuard mode: intercept a whole phone with one QR code

Pro feature. WireGuard mode needs Akev Pro or its 14-day trial. Without a licence it doesn't run, and its settings and keys stay stored, so configured devices work again as soon as you enter a key.

Proxy settings only reach apps that honour them, and on iOS they have to be typed into every Wi-Fi network by hand. WireGuard mode removes that step: Akev runs a small WireGuard server (in userspace — no root, no changes to this computer's network configuration), you scan a QR code with the official WireGuard app, and from then on all of the device's TCP traffic goes through Akev — every app, on any network the phone can reach this computer from.

It is made for the WireGuard apps for iOS, Android, macOS, Windows and Linux, so it is also a way to capture a whole second computer or VM.

Not yet tried on a physical phone. WireGuard mode is tested end to end with a userspace WireGuard client (the same protocol the official apps speak), not yet with a real phone. If something doesn't work on yours, please open an issue. It captures TCP traffic: QUIC (HTTP/3) is dropped so apps fall back to TCP, and other UDP is relayed without being recorded (see what gets intercepted).

Set up

  1. Connect → WireGuard (phones & any device) and switch on WireGuard server. Akev listens on UDP port 51820 (change it in the panel's Server section).
  2. On the device install WireGuard (App Store / Google Play / F-Droid / wireguard.com).
  3. Tap + → Create from QR code (iOS) or Scan from QR code (Android) and scan the code in the panel. On desktops, use Download .conf and Import tunnel(s) from file (or sudo wg-quick up ./akev.conf on Linux).
  4. Switch the tunnel on. The panel shows Device connected with the device's address, the time of the last handshake and the bytes transferred.
  5. For HTTPS, the device must trust the Akev CA. With the tunnel on, open http://akev.cert in Safari / Chrome — the setup page comes through the tunnel — and install the certificate:
    • iOS: download the profile → Settings → Profile Downloaded → Install, then Settings → General → About → Certificate Trust Settings → enable full trust for the Akev CA.
    • Android: download the certificate → Settings → Security → Encryption & credentials → Install a certificate → CA certificate. Apps targeting Android 7+ only trust user CAs if their network security config allows it (debug builds usually do; browsers always do).

Traffic from the device appears in Traffic with source wireguard (filter with source:wireguard); the exchange detail's Connection section shows WireGuard tunnel and the device's tunnel address (10.0.0.2:<port>).

If the computer has several network addresses (Wi-Fi, Ethernet, VPN), pick the one the device can reach in the Endpoint menu above the QR code — the code changes accordingly. Your firewall must allow incoming UDP on the WireGuard port.

What gets intercepted

Traffic What Akev does
TCP — HTTP/1.x, HTTP/2, WebSockets, SSE Intercepted, recorded, rules and breakpoints apply — exactly like a client using the proxy with CONNECT to the same destination.
TCP — TLS Decrypted with a certificate for the client's SNI (needs the Akev CA on the device), or passed through untouched for hosts in TLS passthrough. Clients that reject Akev's certificate fail the handshake; it is recorded as a TLS failure.
TCP — anything else (SSH, SMTP, databases, MQTT…) Tunnelled byte-for-byte to the original destination and recorded as a tunnel row.
DNS (UDP/TCP to 10.0.0.53) Answered by resolving the name on this computer (system resolver configuration, hosts file, getaddrinfo fallback). akev.cert resolves into the tunnel.
QUIC / HTTP/3 (UDP 443) Dropped, so apps fall back to HTTP/2 or HTTP/1.1 over TCP — which Akev intercepts.
Other UDP (NTP, games, VoIP, DNS to other resolvers) Relayed from this computer, not recorded.
ICMP (ping) Dropped.

The proxy reaches servers by the hostname the device used (the Host header or TLS SNI) on the original port, through Akev's own upstream path — so DNS overrides, upstream proxies and client certificates from Settings apply. Connections without a name (an IP-only request without Host, TLS without SNI) go to the original destination IP.

Good to know

  • One configuration = one device. The configuration contains a single client key; a second device importing the same QR code takes the tunnel over from the first. New keys (Server section, or POST /api/wireguard/regenerate) revokes every configuration handed out so far.
  • Keep the QR code private. It contains the device's private key; anyone with it can route their traffic through your Akev while the server is on — and, like any client of the proxy, reach services listening on this computer (including 127.0.0.1).
  • The tunnel routes everything. Switch it off in the WireGuard app when you're done — while it's on and Akev is stopped (or WireGuard mode is off), the device has no internet.
  • Certificate-pinned apps refuse Akev's certificate (their requests show as TLS failures). Add their hosts to TLS passthrough so they keep working untouched.
  • Akev sends IP packets of at most 1420 bytes into the tunnel (the WireGuard apps' default MTU) and honours the TCP MSS the device announces.
  • Keys live in wireguard.json in the data directory (readable only by you); they survive restarts, so a device configured once keeps working.

Settings & API

settings.proxy.wireguard = { enabled: false, port: 51820, bindAddress?: string } (bindAddress absent = all interfaces). The server follows the settings live; it starts with Akev when enabled. A port that's in use is reported in the panel (and GET /api/wireguard error) instead of failing the settings change.

  • GET /api/wireguard[?host=] — status, keys, client configuration / QR payload, peer handshake state, counters.
  • PUT /api/wireguard — { enabled?, port?, bindAddress? }.
  • POST /api/wireguard/regenerate — new keys.
  • GET /api/wireguard/config[?host=] — the .conf file.
  • POST /api/interceptors/wireguard/activate / deactivate — the same switch, for scripts and MCP-style tooling.

See the HTTP API for the payloads.

How it works

Akev's WireGuard server is the akev-wireguard crate, modelled on mitmproxy's WireGuard mode: boringtun implements the protocol for the single client peer, and decrypted IP packets go to a smoltcp TCP/IP stack that accepts connections to any address — for every new SYN it creates a socket listening on exactly that destination, so the device completes the handshake as if it had reached the real server. Each connection becomes a byte stream whose local address is the original destination and is handed to the proxy as if it had arrived through a CONNECT tunnel to that address. Backpressure works end to end: when the proxy doesn't read, the TCP window towards the device closes.

cargo run --release -p akev-wireguard --example wg_smoke -- 127.0.0.1:51820 <data-dir> --https example.com --bench 64 acts as a device (no root needed) against a running Akev.

Type to search guides, the CLI and the API.