WireGuard for Kobo eReaders

Run a WireGuard-based TCP proxy on a Kobo eReader using wireproxy, without requiring kernel TUN support. This project is designed for stock Kobo devices where CONFIG_TUN is unavailable. Instead of creating a real wg0 interface on the Kobo, wireproxy runs WireGuard in userspace and exposes one or more local TCP tunnels.

---

Why?

Kobo devices ship with Linux kernels that do not include TUN support, making a normal WireGuard client impossible.

Instead of patching the kernel or installing custom firmware, this project runs WireGuard entirely in userspace using WireProxy.

This allows your Kobo to securely access services through a WireGuard tunnel while remaining completely stock.

---

What this does

Example flow:

Kobo app
  |
  | https://your-domain.example.com
  v
127.0.0.1:443
  |
  | wireproxy TCPClientTunnel
  v
WireGuard peer
  |
  v
192.168.100.10:443
  |
  v
Reverse proxy / service

The optional /etc/hosts override maps your hostname to 127.0.0.1, so applications can keep using a normal HTTPS hostname while the TCP connection is forwarded through WireGuard.

Requirements

On the Kobo:

• SSH/root access
• NickelMenu (optional, but recommended)
• wireproxy ARMv7 static binary
• Working Wi-Fi

On the WireGuard side:

• Existing WireGuard peer/server
• A public endpoint reachable from the Kobo
• A destination TCP service reachable from that WireGuard peer

Build wireproxy for Kobo

On Ubuntu/Debian:

sudo apt update
sudo apt install -y git golang-go

git clone https://github.com/octeep/wireproxy.git
cd wireproxy

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 \
go build -trimpath -ldflags="-s -w" \
-o wireproxy ./cmd/wireproxy

file wireproxy

Expected:

ELF 32-bit LSB executable, ARM, EABI5, statically linked

Copy the resulting wireproxy binary into this project folder before running setup.

Kobo WireGuard peer example

Server-side peer:

[Peer]
PublicKey = <KOBO_PUBLIC_KEY>
AllowedIPs = 10.0.0.2/32

The Kobo-side address must match:

Address = 10.0.0.2/32

Quick install

Copy this entire folder to the Kobo, for example:

/mnt/onboard/kobo-wireproxy-sanitized/

Make sure the wireproxy binary is inside that folder.

Then run:

cd /mnt/onboard/kobo-wireproxy-sanitized
chmod +x setup.sh
./setup.sh

The installer asks for:

• Kobo private key
• WireGuard server public key
• WireGuard endpoint
• Kobo VPN address
• Allowed IP / target network
• Local bind port
• Remote target IP/port
• Optional hostname override

It installs files under:

/mnt/onboard/.adds/wireproxy/

and NickelMenu entries under:

/mnt/onboard/.adds/nm/

Example generated wireproxy config

[Interface]
PrivateKey = <CLIENT_PRIVATE_KEY>
Address = 10.0.0.2/32

[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
Endpoint = YOUR_SERVER_PUBLIC_IP:51820
AllowedIPs = 192.168.100.10/32
PersistentKeepalive = 25

[TCPClientTunnel]
BindAddress = 127.0.0.1:443
Target = 192.168.100.10:443

Hostname override

If you enter:

your-domain.example.com

the start script adds:

127.0.0.1 your-domain.example.com

to /etc/hosts.

When WireProxy is stopped, that exact line is removed.

This lets an application keep using:

https://your-domain.example.com

while the actual TCP connection is sent through the WireGuard tunnel.

NickelMenu

After setup and reboot, NickelMenu should show:

WireGuard ON
WireGuard OFF

These call:

/mnt/onboard/.adds/wireproxy/start.sh
/mnt/onboard/.adds/wireproxy/stop.sh

Manual commands

Start:

/mnt/onboard/.adds/wireproxy/start.sh

Stop:

/mnt/onboard/.adds/wireproxy/stop.sh

Check process:

pidof wireproxy

Watch log:

tail -f /mnt/onboard/.adds/wireproxy/wireproxy.log

Foreground debug:

cd /mnt/onboard/.adds/wireproxy
./wireproxy -c config.conf

Troubleshooting

bind: cannot assign requested address

Bring loopback up:

ip link set lo up

The included start script does this automatically.

WireGuard handshake fails

Check:

tail -f /mnt/onboard/.adds/wireproxy/wireproxy.log

You want:

Received handshake response

On the server:

sudo wg show

TCP tunnel does not work

On the WireGuard peer/server, use:

sudo tcpdump -ni wg0 'host 10.0.0.2 and tcp port 443'

If you see SYN/SYN-ACK and application data, WireGuard and WireProxy are forwarding traffic correctly.

HTTPS resets

If TCP works but HTTPS resets, inspect the TLS endpoint separately. That is usually not a WireGuard routing problem.

Security

Never publish:

• WireGuard private keys
• Preshared keys
• Real private infrastructure addresses if you consider them sensitive
• Public IPs you do not want exposed

This repository intentionally uses documentation-only example addresses:

• 10.0.0.0/24
• 192.168.100.0/24
• your-domain.example.com
• YOUR_SERVER_PUBLIC_IP

Notes

wireproxy is not a full VPN interface. It forwards traffic through userspace WireGuard using local proxy/tunnel endpoints.

That makes it useful on Kobo firmware where kernel TUN support is unavailable.