# MicroWARP Docker Guide for a Lightweight WARP SOCKS5 Proxy

> MicroWARP is a Docker-based Cloudflare WARP SOCKS5 proxy for small Linux hosts and sidecar deployments. Its default WireGuard path uses the Linux kernel, while an optional MASQUE path supports deployments where WireGuard UDP is restricted.

**ccbkkb/MicroWARP** — 🚀 An 800KB RAM ultra-lightweight Cloudflare WARP SOCKS5 proxy in Docker. 仅需 800KB 内存的纯内核态 Cloudflare WARP 代理 - Docker

- Repository: https://github.com/ccbkkb/MicroWARP
- Stars: 1,450 · Forks: 188
- Language: Shell
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ccbkkb-microwarp

## MicroWARP's Target Deployment and Main Trade-off

MicroWARP addresses a specific gap between Cloudflare's full WARP client and a small server-side proxy. It packages WARP connectivity and a SOCKS5 listener in one Docker container so an application can send outbound traffic through Cloudflare WARP without installing a desktop client on the host. The documented use cases include routing crawlers or API gateways through WARP, using WARP as a server's default egress path, acting as a Docker sidecar, and reaching IPv6-only destinations through the WireGuard route.

The principal trade-off is architecture. The default path relies on Linux kernel WireGuard through `wg0` and the pure C `microsocks` program. This keeps the data path small, but it also means the container manages privileged networking state. The Compose example adds `NET_ADMIN` and `SYS_MODULE`, enables forwarding, and changes IPv4 and IPv6 sysctls. An operator must therefore accept a container with substantial authority over its network namespace in exchange for a low-overhead proxy design.

The README presents MicroWARP as a lightweight alternative to images built around Cloudflare's official `warp-cli` daemon. Its published comparison reports approximately `800 KiB` for the WireGuard path and contrasts that with approximately `150 MB` for the official-daemon image. Those figures are repository claims and examples, not a result generated for this article. The correct reading is that MicroWARP may suit constrained hosts, especially on its default route, but memory use changes substantially when the optional MASQUE client is selected.

## How the WireGuard and MASQUE Paths Carry SOCKS5 Traffic

On the WireGuard path, MicroWARP configures a Linux interface named `wg0`. The documented configuration permits both IPv4 and IPv6 default routes through WARP, using `0.0.0.0/0` and `::/0`, and applies IPv6 policy routing for reply traffic. A client connects to the SOCKS5 listener on port `1080`. The `microsocks` process accepts that connection and forwards the request through the container's WARP-connected network path.

The tunnel is not the same as the proxy listener. WireGuard supplies the encrypted network connection, while `microsocks` supplies the SOCKS5-facing service. This separation explains why the Compose file needs both networking capabilities and a persistent volume. WireGuard configuration is stored under `/etc/wireguard`, and the named `warp-data` volume keeps that directory when the container is replaced.

The optional MASQUE path changes the transport and the forwarding implementation. Set `TUNNEL_PROTOCOL=masque` to select `usque`, which uses CONNECT-IP over HTTP/3. The README says this can help when WireGuard UDP is blocked or subject to quality-of-service policy. The default `MASQUE_PROXY_MODE=l4-socks` is lighter but TCP-only. The alternative `MASQUE_PROXY_MODE=socks` uses a full gVisor L3 stack and supports TCP and UDP, at a higher memory cost. `MASQUE_HTTP2=1` enables TCP and HTTP/2 fallback, but the documentation says it requires `MASQUE_PROXY_MODE=socks`.

This design gives operators a meaningful protocol choice, but it does not make the modes interchangeable. Applications requiring UDP must not be assigned to the lighter `l4-socks` mode without verifying their actual requirements. Likewise, selecting MASQUE should be based on network conditions rather than on the assumption that it is always faster or smaller.

## Installing MicroWARP with Docker Compose

The repository provides a Compose definition for a first deployment. Save the following as `docker-compose.yml`. It uses the published image, keeps the SOCKS5 port on host loopback, grants the capabilities required by the tunnel, enables the documented IPv4 and IPv6 sysctls, and persists configuration in `/etc/wireguard`.

The credentials shown here are the example values present in the repository's Compose comments. Replace them with values appropriate for the deployment. MicroWARP refuses to start without `SOCKS_USER` and `SOCKS_PASS` unless `ALLOW_NO_AUTH=1` is explicitly configured.

```yaml
services:
  microwarp:
    image: ghcr.io/ccbkkb/microwarp:latest
    container_name: microwarp
    restart: always
    ports:
      - "127.0.0.1:1080:1080"
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.default.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
    environment:
      - SOCKS_USER=admin
      - SOCKS_PASS=123456
    volumes:
      - warp-data:/etc/wireguard

volumes:
  warp-data:
```

Start the service with the command documented in the README:

```bash
docker compose up -d
```

After startup, the expected endpoint is `127.0.0.1:1080` on the Docker host. The README does not define a health-check command or a `curl` test for the SOCKS5 listener, so verify startup through container logs and then connect with the SOCKS5 client used by the application. Keep the loopback mapping unchanged unless the proxy is protected and access from other hosts is intentional.

## IPv6, Tailscale Routes, and MASQUE Configuration Constraints

IPv6 is enabled by default on the WireGuard route. Set `ENABLE_IPV6=0` when an IPv4-only deployment is required. The Compose example also enables IPv6 inside the container and sets forwarding, so changing only an application setting may not be sufficient if the surrounding Docker network disables IPv6.

The WireGuard path includes special handling for Tailscale-style overlay networks. After bringing up WARP, MicroWARP restores asymmetric routing for `100.64.0.0/10` and `fd7a:115c:a1e0::/48`. Those ranges can be configured with `TAILSCALE_CIDR` and `TAILSCALE_CIDR_V6`. This is useful when the container must coexist with an overlay VPN, but it also means MicroWARP is changing routing policy rather than simply providing a standalone SOCKS5 process.

MASQUE has several mode-specific constraints. `MASQUE_PROXY_MODE=l4-socks` is the documented lighter choice and handles TCP. The full `socks` mode supports TCP and UDP through gVisor L3 but consumes more memory. `MASQUE_SNI` applies only to full `socks` mode and is ignored by `l4-socks`. `MASQUE_MTU` is likewise documented for the full mode. `GOMEMLIMIT=512MiB` is a soft Go memory cap, not a promise that the MASQUE process will remain below that amount.

The optional `WARP_JWT`, `WARP_LICENSE`, `USQUE_DEVICE_NAME`, and `USQUE_CONFIG` variables concern MASQUE registration and identity. The documentation does not describe token rotation, registration failure recovery, or how to migrate identity between images. Operators selecting MASQUE should test registration during initial deployment and retain the `/etc/wireguard` volume.

## Operational Limits, Alternatives, and Upgrade Work

MicroWARP is not a general Cloudflare client replacement in the documentation. Its documented scope is a SOCKS5 proxy with a WireGuard default and an optional MASQUE implementation. The README does not provide a compatibility table for every `warp-cli` feature, nor does it document rollback, dashboard management, or a complete failure-recovery procedure. That makes it important to validate the specific behavior an application needs.

The main alternative described by the README is an image based on `caomingjun/warp` and Cloudflare's official daemon. The difference is not merely branding. The official daemon performs WARP processing in userspace, while MicroWARP's default uses kernel WireGuard and `microsocks`. An operator may choose the official client when its own tooling and behavior are required, especially if MicroWARP's kernel capabilities are unacceptable. MicroWARP is the more focused choice when the requirement is a small SOCKS5 sidecar and the host supports its privileged network setup.

Maintenance is visible in the repository history. The last push was on 2026-09-04, and the listed releases are `v0.3.1` on 2026-09-04, `v0.3.0` on 2026-08-12, and `v0.2.0` on 2026-08-08. The repository is not archived. The project is licensed under MIT, which permits use and modification under that license's conditions. The documentation does not promise compatibility between releases or explain a migration process, so upgrading `latest` can change behavior without a documented rollback guarantee.

For an existing deployment, pin a tested image tag if stable operation matters. Retain the `/etc/wireguard` volume, review changes to `entrypoint.sh`, and test both IPv4 and IPv6 clients before replacing a production container. The repository's limited runtime layer and persisted state make upgrade testing inexpensive, but the required capabilities and routing changes still make an upgrade an infrastructure operation rather than a routine application restart.

## Conclusion

MicroWARP is appropriate for operators who need Cloudflare WARP egress from a small Linux Docker host and can grant the required kernel networking privileges. It is a poor fit for hosts that cannot use `NET_ADMIN` and `SYS_MODULE`, applications that need UDP in the lighter MASQUE mode, or teams that do not want to manage WARP state and credentials. Before adoption, verify kernel WireGuard support, test the selected tunnel mode against local network restrictions, and confirm that your client can reach the SOCKS5 listener. The default WireGuard architecture is the clearest choice when low memory use is the priority, but the project still depends on Docker, Linux networking privileges, and image upgrades.

## FAQ

### What does MicroWARP do?

MicroWARP is a Docker container that exposes Cloudflare WARP through a SOCKS5 proxy. Its default route uses Linux WireGuard with `microsocks`, while the optional MASQUE route uses `usque`.

### How do I install MicroWARP with Docker Compose?

Create the documented Compose service, publish port `1080`, grant `NET_ADMIN` and `SYS_MODULE`, mount `/etc/wireguard`, and set `SOCKS_USER` and `SOCKS_PASS`. Then run `docker compose up -d`.

### Does MicroWARP support UDP?

The default WireGuard route documents dual-stack IPv4 and IPv6 routing. For MASQUE, `l4-socks` is TCP-only, while `MASQUE_PROXY_MODE=socks` provides TCP and UDP through a heavier gVisor L3 mode.

## Sources

- [ccbkkb/MicroWARP on GitHub](https://github.com/ccbkkb/MicroWARP)
- [Issues](https://github.com/ccbkkb/MicroWARP/issues)
- [License: MIT](https://github.com/ccbkkb/MicroWARP/blob/main/LICENSE)
- [README](https://github.com/ccbkkb/MicroWARP/blob/main/README.md)
- [Releases](https://github.com/ccbkkb/MicroWARP/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ccbkkb-microwarp