Goal
Hide the user's home IP from Ace Stream peers by forcing the engine runtime through a user-provided WireGuard tunnel. The engine must fail closed: no tunnel means no engine internet access.
Design
- Build the gateway locally from a pinned official Ubuntu base and distro
wireguard-tools; do not use third-party VPN images or custom cryptography.
- Run the engine in the gateway container's network namespace and publish only
127.0.0.1:6878 for the local API/HLS stream.
- Allow outbound traffic only through WireGuard, except the configured VPN endpoint. Route DNS through the tunnel and block IPv6 leaks.
- Treat imported WireGuard files as untrusted. Parse an allow-list of fields and reject command hooks such as
PreUp, PostUp, PreDown, and PostDown.
- Keep private keys out of Git, process arguments, and diagnostics. Store them in Keychain or a permission-restricted local secret.
- Require a recent WireGuard handshake and verified tunnel egress before reporting the engine ready. Stop playback if tunnel health is lost.
Acceptance criteria
- The engine cannot reach the internet before tunnel readiness or after tunnel failure.
- Ace Stream peers see the VPN exit IP, not the user's home IP.
- IINA can still reach the engine only through
127.0.0.1:6878.
- Unit tests cover configuration validation, command construction, readiness, timeout, and tunnel loss.
- An opt-in integration test proves the kill switch without requiring a real Ace Stream stream.
- Direct networking remains available only as an explicit, clearly labelled mode.
Non-goals
- Operating a VPN service or server.
- Promising anonymity or legal protection.
- Hiding traffic from the chosen VPN provider.
- Routing native Sports/provider requests; those require a system VPN or a separate proxy design.
Goal
Hide the user's home IP from Ace Stream peers by forcing the engine runtime through a user-provided WireGuard tunnel. The engine must fail closed: no tunnel means no engine internet access.
Design
wireguard-tools; do not use third-party VPN images or custom cryptography.127.0.0.1:6878for the local API/HLS stream.PreUp,PostUp,PreDown, andPostDown.Acceptance criteria
127.0.0.1:6878.Non-goals