Docker-Warp-Socks: Cloudflare WARP as a Containerized SOCKS5 Proxy

What Docker-Warp-Socks Does

Docker-Warp-Socks solves a practical problem: Cloudflare's official warp-cli only supports AMD64 machines, and running it on a remote server carries a risk of losing network connectivity if misconfigured. Docker-Warp-Socks wraps the WARP connection inside a container, isolating any connectivity risk from the host and extending support to arm, arm64, ppc64le, s390x, and riscv64 architectures in addition to amd64.

The container registers a WARP device, tunnels all traffic through Cloudflare's network, and exposes the result as a SOCKS5 proxy on port 9091. It also accepts HTTP and HTTPS proxy connections on the same port. Any application that can route through a SOCKS5 proxy can use this container as a gateway to Cloudflare WARP without installing warp-cli on the host.

Version 7: sing-box Core and Reduced Privileges

Version 7 is a significant internal change. The README describes the v7 changes as: rich multi-architecture support, light start without NET_ADMIN or SYS_MODULE capabilities or `/lib/modules` volume mounts, more secure bootstrap without `privileged` acquisition, self-contained WARP registration without fetching third-party scripts at runtime, and a core upgrade to SagerNet/sing-box v1.13.x.

The Dockerfile confirms that sing-box is downloaded and installed during the image build. It resolves the latest 1.13.x stable release from the GitHub API, with a fallback to the pinned v1.13.19 if the API is unavailable. The architecture detection covers x86_64, aarch64, armv7l, armv6l, arm, ppc64le, s390x, and riscv64.

V7 also adds rule-action routing with `sniff`, `hijack-dns`, and `route` actions; auto-detect interface with a default domain resolver; ICMP/ping support over the tunnel; optimistic DNS cache using a persistent `cache_file`; and TLS fragment route options from sing-box 1.13.x. Mixed HTTP, HTTPS, and SOCKS protocol support on port 9091 is included.

Quick Start and Docker Compose Deployment

The simplest deployment launches the container with a single command that maps port 9091 and sets it to restart automatically:

docker run --restart=always -itd \
    --name warp-socks \
    -p 9091:9091 \
    ghcr.io/mon-ius/docker-warp-socks

Verify connectivity by curling the Cloudflare trace endpoint through the proxy and checking for `warp=on` in the response:

curl -x "socks5h://127.0.0.1:9091" -fsSL "https://www.cloudflare.com/cdn-cgi/trace"

For Docker Compose, the `docker-compose.yml` in the repository adds a health check that automates this verification:

services:
    warp-socks:
        image: ghcr.io/mon-ius/docker-warp-socks
        container_name: warp-socks
        restart: always
        ports:
            - "9091:9091"
        healthcheck:
            test: ["CMD", "curl", "-x", "socks5h://127.0.0.1:9091", "-fsSL", "https://www.cloudflare.com/cdn-cgi/trace"]
            interval: 30s
            timeout: 10s
            retries: 5
            start_period: 10s

The image is published on both Docker Hub (`monius/docker-warp-socks`) and GitHub Container Registry (`ghcr.io/mon-ius/docker-warp-socks`). A GitHub Actions workflow automatically publishes multi-arch builds for release branches and version tags.

Advanced Configuration: Authentication, Custom Ports, and Upstream Proxy

The container supports several optional configurations. To add SOCKS5 authentication, pass `SOCK_USER` and `SOCK_PWD` environment variables. To change the proxy port, set `NET_PORT`. Both are environment variables passed to `docker run` with `-e`.

The v7 container also supports routing its outbound requests through an upstream HTTP proxy, which is useful in environments where Docker containers cannot connect directly to the internet. This is configured via environment variables defined in the `entrypoint.sh` script.

The README notes a historical WARP Plus license key feature via `WGCF_LICENSE_KEY`, but notes that due to policy changes, the `plus` flag no longer appears in the Cloudflare trace endpoint. Instead, a successful WARP Plus connection now shows `sliver=xxx-tier1` in the trace output.

Cloudflare WARP vs. a Traditional VPN

Cloudflare WARP is a WireGuard-based service that routes traffic through Cloudflare's network. It differs from a traditional VPN in scope and purpose: it does not hide the user's identity from Cloudflare, and its primary purpose is performance and security on the Cloudflare network rather than anonymity. The README's trust note is relevant here: the Docker-Warp-Socks container connects to Cloudflare's network, so Cloudflare can see all traffic passing through it.

A traditional VPN like WireGuard or OpenVPN run on a private server gives more control over who sees the traffic, at the cost of needing to manage the server and IP reputation. Docker-Warp-Socks is the right choice when the goal is to use Cloudflare's network for access to services that are routed through it, not for anonymizing traffic from Cloudflare itself.

The container's GPL-3.0 license requires that anyone distributing a modified version make the source available.

Limitations and Maintenance

The Dockerfile fetches sing-box dynamically from the GitHub API during the image build. If the GitHub API is unreachable at build time or returns no matching 1.13.x release, the Dockerfile has a fallback to the pinned v1.13.19. In restricted network environments where api.github.com is blocked, the pinned fallback will be used without notice.

The container has no built-in rate limiting or per-client connection controls. It runs as a single shared SOCKS5 endpoint, so any process with network access to port 9091 can route traffic through it. In multi-tenant or shared environments, the SOCKS5 authentication option (via SOCK_USER and SOCK_PWD) should be configured.

The repository has no GitHub releases. The Dockerfile label shows version 7.0.0 and the last push was on 2026-08-18. The image is hosted on GHCR with a multi-architecture build covering six architectures. The base image is Alpine Linux 3.24.

Editorial conclusion

Docker-Warp-Socks is the right choice for developers who need Cloudflare WARP routing in a containerized environment on non-AMD64 hardware or without privileged access. The health check command (curling the Cloudflare trace endpoint through the proxy and looking for `warp=on`) gives a concrete verification step after deployment. Confirm the sing-box 1.13.x stable release is resolvable from the GitHub API at deploy time, since the Dockerfile fetches it dynamically; a network restriction that blocks api.github.com will fall back to the pinned v1.13.19.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Mon-ius/Docker-Warp-Socks on GitHub
4. Project website
5. README