Skip to content
The Gateway

FAQ

Platform & licensing

Section titled “Platform & licensing”

Is it open source?

Section titled “Is it open source?”

No. The Gateway is private, proprietary software. Binaries are provided for linux/amd64 and linux/arm64. Source builds are supported for licensees. For access or commercial inquiries, contact us.

Does it run on Windows or macOS?

Section titled “Does it run on Windows or macOS?”

No. The dataplane is Linux-only — it uses in-kernel WireGuard, nftables, ip rule, and tc. You can manage a Linux Gateway from any OS; you can’t run the daemon on one.

Will it run on a Raspberry Pi 3 / Zero?

Section titled “Will it run on a Raspberry Pi 3 / Zero?”

No. The Pi 4 (or newer) is the minimum: 64-bit, 2 GB+ RAM, in-kernel WireGuard. A Pi 3 lacks the throughput and the RAM headroom for the splitting engine at higher privacy levels.

Why Linux 5.15+ specifically?

Section titled “Why Linux 5.15+ specifically?”

WireGuard went in-kernel in 5.6, and nftables numgen vmap patterns are reliable from 5.15. Older kernels work for small deployments but lose the kernel-fast splitting path.

Networking

Section titled “Networking”

Does it replace my home router?

Section titled “Does it replace my home router?”

It can, in primary mode (The Gateway runs DHCP and is the LAN’s default route). More commonly it runs in embedded mode — sitting inline between an ISP router and your switch — so you don’t have to touch the ISP-provided box.

Can I run it on the same box that runs other services?

Section titled “Can I run it on the same box that runs other services?”

Yes, but the daemon owns its nftables table and its routing tables. If you have another tool managing nftables (Docker, ufw, firewalld), there will be drift. The reconciler will fight whatever else is touching the kernel. Don’t.

Section titled “Does the splitting engine bond two ISP uplinks?”

No — it does per-connection load balancing, not channel bonding. A single TCP flow uses one link; new flows distribute across links. See the Dual-WAN use case for why this is what you almost always actually want.

Can I federate two gateways behind NAT?

Section titled “Can I federate two gateways behind NAT?”

Yes. Both join the same mesh (Tailscale / Headscale); federation rides whatever connectivity the mesh provides. STUN / DERP relays handle NAT traversal. Federation itself doesn’t stand up its own dataplane tunnel — it reuses the mesh layer.

How do I handle hotel / café captive portals?

Section titled “How do I handle hotel / café captive portals?”

gwctl captive runs three standard probes (Google, Firefox, Microsoft connectivity-check URLs) and reports whether the network requires login plus the portal URL. The daemon won’t auto-bypass the kill-switch — add a short-lived direct exception for the captive endpoint, complete the portal, and let the TTL expire. The travel-router use case walks through it.

How does gwctl authenticate?

Section titled “How does gwctl authenticate?”

It doesn’t, on its own — gwctl sends no Authorization header. With auth.enabled: false (the install default) every request is admin so gwctl just works. With auth on, the loopback-CIDR bypass elevates GET/HEAD/OPTIONS only, so read commands (gwctl tunnels, gwctl status) still work from the daemon host — but anything that mutates state (up/down/apply/create) returns 401. For state-changing operations under enforced auth, use curl against the REST API directly with Authorization: Bearer <api-key>.

Privacy & security

Section titled “Privacy & security”

Is the kill-switch global or per-policy?

Section titled “Is the kill-switch global or per-policy?”

Per-policy. A failing tunnel only blackholes traffic for policies bound to it; the rest of the LAN keeps working. This is by design — it lets you protect sensitive devices without taking the household offline.

What’s a “fail-closed” policy in plain English?

Section titled “What’s a “fail-closed” policy in plain English?”

If the egress for that policy is down, drop the traffic instead of leaking it through your default route. The kill-switch enforces this in nftables, ahead of the routing decision.

Can a misbehaving script bypass the firewall?

Section titled “Can a misbehaving script bypass the firewall?”

The reconciler scans nftables and ip rule every minute (configurable down to 5 s) and re-applies its desired state. A script that flushes a chain wins for at most that interval. The kill-switch sits at prerouting priority -1 so it fires before anything else in the kernel.

Does the leak checker catch WebRTC leaks?

Section titled “Does the leak checker catch WebRTC leaks?”

Yes. The checker probes UDP STUN endpoints and verifies that traffic is dropped when block_webrtc is on. A failing webrtc_stun test trips the built-in leak-detected rule, which fires through the configured webhook + Telegram.

Operations

Section titled “Operations”

What happens to in-flight TCP connections when a tunnel cycles?

Section titled “What happens to in-flight TCP connections when a tunnel cycles?”

They die. WireGuard rekeys won’t break them, but a manual gwctl tunnels down <id> && gwctl tunnels up <id> will. Long-lived idempotent connections (SSH, video) will reconnect transparently; one-shot HTTP requests fail and the client retries. Plan splitting rotations accordingly — at level 5 (60-second rotation), short-lived flows benefit most.

How do I take a backup?

Section titled “How do I take a backup?”

Two distinct paths. gwctl backup export > /path/to/file.json writes a plaintext sanitized snapshot (secrets stripped) — good for inspection / sharing. For an encrypted backup with secrets, go through the REST API: POST /api/v1/backup/export-encrypted with a {"passphrase": "..."} body returns an AES-256-GCM ciphertext (PBKDF2-HMAC-SHA256, 100k iters, per-export salt). Restore: gwctl backup import <plaintext-file.json> for the sanitized path; for encrypted, decrypt externally first (no encrypted-import endpoint today). See Backup for full mechanics.

How do I roll back a bad config change?

Section titled “How do I roll back a bad config change?”

Snapshots: every successful apply creates a local snapshot. gwctl snapshots lists them; gwctl rollback <snapshot> reverts. Use this before restoring from a full backup — snapshots are cheap and don’t touch unrelated state.

Is the audit log tamper-evident?

Section titled “Is the audit log tamper-evident?”

The log is append-only at the daemon level — there’s no DELETE endpoint, operators can adjust retention but not redact specific entries. The on-disk SQLite file itself is not cryptographically chained. If you need provable tamper-evidence, periodically GET /api/v1/audit from a remote auditor, sign the dump there, and store the signatures off-box.

Performance

Section titled “Performance”

Will privacy level 5 saturate my Pi 4?

Section titled “Will privacy level 5 saturate my Pi 4?”

A Pi 4 can keep up with a single client at level 5 (≈100% overhead, 5 Mbit HTB shape, 10 pps cover). It won’t keep up with five clients at level 5. Pick levels per policy; only the policies that need it pay the cost.

Section titled “Why is my throughput lower than the upstream link?”

Three usual suspects: (1) WireGuard’s per-CPU bottleneck (a Pi 4 caps at ~300 Mbit per core); (2) MTU mismatch — check interface MTU matches the tunnel’s effective MTU; (3) HTB shaping at privacy level 3+. The Dashboard’s per-policy bandwidth graph isolates which.

Comparisons

Section titled “Comparisons”

How is this different from pfSense / OPNsense?

Section titled “How is this different from pfSense / OPNsense?”

Both are excellent firewalls. The Gateway is a programmable gateway: per-device routing, kill-switch reference counting, traffic splitting with privacy levels, and federation are first-class objects in a REST API — not hand-edited rules. If you want a generic firewall, use pfSense / OPNsense. If you want a coherent policy-driven gateway, use The Gateway.

How is it different from Tailscale on its own?

Section titled “How is it different from Tailscale on its own?”

Tailscale is a mesh control plane. The Gateway uses it (or self-hosted Headscale) for inter-node connectivity, but adds the rest of the stack: a DNS plane, a firewall, the splitting engine, the kill-switch, bridges, federation. You can run both happily.

Is the AI assistant required?

Section titled “Is the AI assistant required?”

No. It’s optional. The validator endpoint exists if you have an Ollama (or compatible) endpoint configured; ignore it otherwise. Nothing else depends on it.

Section titled “Related”