Docker-Warp-Socks: a CloudFlare WARP socks5 proxy in one container

What Docker-Warp-Socks actually solves

CloudFlare WARP is a WireGuard-based tunnel to Cloudflare's network. The official warp-cli only supports amd64 machines, and the README points at a Cloudflare documentation change that it says is prone to causing connection loss on remote machines, with the suggested remedy being a fresh install inside a container or a reboot through the panel. Docker-Warp-Socks takes that advice and packages it: an Alpine Linux image that registers with WARP, brings up the tunnel, and exposes a local proxy so other software can route through it.

The target user is someone who already runs a proxy service and wants WARP as an extra egress path, not as a replacement for their existing setup. The README describes the image as acting "just like a plugin" alongside a running proxy. The topics on the repository (chatgpt, cloudflare, docker, warp-plus, wireguard) point at the same audience: people whose tools are blocked or degraded on their normal connection and who want a second route they can point at one process rather than the whole host.

The image is published as ghcr.io/mon-ius/docker-warp-socks and built for linux/arm, linux/arm64, linux/amd64, linux/ppc64le, linux/s390x and linux/riscv64. That breadth matters because the official client does not cover those.

How the container routes traffic through WARP

The core is SagerNet/sing-box v1.13.x, which the README describes as built on WireGuard endpoints and a typed DNS engine. The Dockerfile resolves a sing-box release at build time: it queries the GitHub releases API for SagerNet/sing-box, filters to non-prerelease tags starting with v1.13., and picks the asset whose name contains the matching linux-<arch> string. If nothing resolves, the build falls back to a pinned v1.13.19 URL.

That build-time resolution is worth understanding before you rely on it. The image you pull is the image that was built when the maintainer last built it, so the sing-box version is whatever the API returned at that moment, not whatever is current when you run docker pull. Pinning happens only on the fallback path.

Above sing-box sits the proxy listener. Version 7 of the image serves mixed http, https and socks protocols on port 9091, which is why both socks5h:// and http:// URLs work against the same port in the README's verification commands. The README also lists rule-action routing with sniff, hijack-dns and route, an auto_detect_interface setting, a default_domain_resolver, ICMP over the tunnel, an optimistic DNS cache with a persistent cache_file, and a bypass rule action. Those are sing-box features surfaced through this image's configuration rather than anything the project wrote itself.

The claim that matters most is the negative one: version 7 starts without NET_ADMIN, SYS_MODULE, a /lib/modules mount, or extra net dependencies, and registers with WARP itself rather than fetching a third-party bootstrap script at runtime. The commented-out v1 instructions in the README show the old shape, with --privileged, --cap-add NET_ADMIN, --cap-add SYS_MODULE, --sysctl net.ipv4.conf.all.src_valid_mark=1 and -v /lib/modules:/lib/modules all present. The current quick start has none of them. That is the real change between generations of this image, and it is what makes it usable on hosts where you cannot load kernel modules.

Installing Docker-Warp-Socks and checking that WARP is on

The README's quick start is a single docker run. It publishes port 9091 and restarts the container automatically.

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

If you prefer Compose, the README gives a service definition with the same port and a healthcheck that curls the Cloudflare trace endpoint through the proxy every 30 seconds, with a 10 second timeout, 5 retries and a 10 second start period.

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

Verification is the part people skip and then misdiagnose. The README's own test is to fetch the Cloudflare trace endpoint through the proxy, over both the socks5h and http schemes, and to look for warp=on in the response.

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

A first real use is to point one client at that port instead of changing the host's routing. The README notes the image is meant to sit alongside an existing proxy service, so the practical pattern is a per-application proxy setting or a proxy chain, not a system-wide default route. Note the socks5h scheme: the h means DNS is resolved by the proxy, which is what you want if the point is to keep name resolution on the WARP side.

Where Docker-Warp-Socks breaks down

The first limitation is the egress itself. WARP is a shared network, and the README offers no way to pin your exit IP. If you need a fixed address for allowlisting, or an address you can attribute in a log, this image does not give you one. It is the wrong tool for that job regardless of how well the container runs.

The second is the registration lifecycle. The README states that version 7 performs self-contained WARP registration with no third-party redirector and no remote bootstrap script fetched at runtime, which is a genuine improvement over the older approach, but it also means the tunnel identity lives inside the container. The README does not document how to export, back up or transfer that registration, and it does not document rollback. If you delete the container, you should assume you are registering again rather than resuming.

The third is that Cloudflare can change what the trace endpoint reports. The README's own advanced section notes that, after a policy change, the plus flag no longer appears when checking the trace endpoint and that a sliver=xxx-tier1 value indicates success instead. Any monitoring you build around a specific field in that output is monitoring a third party's response format, not this project's API.

Finally, the README is not a specification. The feature list is a bulleted summary of sing-box capabilities, and the repository has no retrieved releases, so there is no changelog to read for a given tag. If you need to know exactly which sing-box build is inside a given image digest, the Dockerfile's build-time API query is the only place that logic lives, and it does not record what it resolved.

Docker-Warp-Socks versus running warp-cli on the host

The obvious alternative is Cloudflare's own warp-cli, installed directly on the machine. The difference is not features, it is blast radius. warp-cli configures the host's networking, so a failure takes the host's connectivity with it, and the README's own criticism of the official guide is that it risks connection loss on remote machines to the point where you may have to reboot through a panel.

Docker-Warp-Socks inverts that. The tunnel lives in a container with its own filesystem and its own proxy listener, and the host keeps its routing. A crash means port 9091 stops answering, and your other traffic is unaffected. You also get the multi-architecture builds, which warp-cli does not offer beyond amd64, and you avoid the kernel-module dependency entirely in version 7.

The cost of that isolation is that WARP is no longer transparent. With warp-cli, applications on the host use the tunnel without knowing it exists. With this image, every client has to be told to use socks5h://127.0.0.1:9091 or the equivalent HTTP proxy setting. For a single tool that is trivial. For a desktop with dozens of applications, it is a configuration project. Choose based on whether you want one process routed or the whole machine.

Maintenance, licensing and what upgrading involves

The repository is not archived and the last push was on 2026-08-18, so it has been touched recently. Beyond that, nothing in the repository supports claims about a release cadence, because no releases were retrieved and the README carries no version history section. There is no published upgrade procedure.

In practice, upgrading means replacing the container with a newer image. Because the Dockerfile resolves sing-box at build time, a rebuild can pull a different sing-box version without any change to the tag you pull. That is convenient for staying current and inconvenient for reproducibility: two builds of the same tag weeks apart need not contain the same sing-box. If you care about that, pin by image digest rather than by tag.

Licensing is GPL-3.0, per the repository's LICENSE file and the badge in the README. The Dockerfile also records org.opencontainers.image.version as 7.0.0 and sets the vendor and author fields to M0nius. GPL-3.0 is a copyleft licence, which matters if you plan to redistribute a modified image rather than just run it. That is a question for your own counsel, not something this article can settle. Note that the image bundles sing-box, whose own licence is separate from this project's.

Editorial conclusion

Adopt it if you want a WARP egress reachable over socks5h://127.0.0.1:9091 without NET_ADMIN, SYS_MODULE or a /lib/modules mount, and if you accept that the egress IP is shared and unguaranteed. Do not adopt it if you need a stable, documented egress address, because the repository does not offer one. Verify first by running the image and checking that the Cloudflare trace endpoint reports warp=on, since that is the project's own stated success condition.

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