# docker-easyconnect: Running Sangfor's EasyConnect and aTrust VPN Inside Docker

> docker-easyconnect wraps Sangfor's proprietary EasyConnect and aTrust VPN clients in Docker containers and exposes SOCKS5 and HTTP proxy endpoints on the host, so any application on the host can route traffic through the VPN without installing the client natively. The last push to the repository was on 2026-03-11, and the README is actively recruiting new maintainers.

**docker-easyconnect/docker-easyconnect** — 使深信服（Sangfor）开发的非自由的 VPN 软件 EasyConnect 和 aTrust 运行在 docker 或 podman 中，并作为网关和/或提供 socks5、http 代理服务

- Repository: https://github.com/docker-easyconnect/docker-easyconnect
- Stars: 5,525 · Forks: 449
- Language: Shell
- License: WTFPL
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/docker-easyconnect-docker-easyconnect

## The Problem: EasyConnect as a Native Client with Broad System Access

EasyConnect is a VPN client developed by Sangfor Technologies that many universities and corporate networks require for remote access. The native Linux and Windows installers take significant control of the host's network stack, routing all traffic through the VPN gateway and often installing kernel drivers or system services. This is disruptive for developers who need VPN access to a specific resource but do not want all their traffic rerouted. docker-easyconnect addresses this by running EasyConnect inside a Docker container that is isolated from the host's network configuration, and exposing only a SOCKS5 proxy on port 1080 and an HTTP proxy on port 8888. Applications that need to reach the VPN-protected network configure those proxies; everything else routes normally.

## Two Container Modes: CLI and GUI with VNC

The project provides two distinct container types. The CLI version supports only username-and-password authentication or hardware fingerprint authentication and runs headlessly. It supports the amd64 architecture only. The GUI version runs the full graphical EasyConnect or aTrust interface inside a VNC server on port 5901, which allows web-based login flows that the CLI cannot handle. The GUI images support amd64, arm64, and mips64el architectures. A VNC client (or a browser with noVNC if the image includes it) connects to localhost:5901 with the password set by the `PASSWORD` environment variable to interact with the login interface. Once authenticated, both modes expose the same SOCKS5 and HTTP proxy endpoints on the host.

## Starting the CLI Container

For username-and-password login on amd64, the README gives this command:

```bash
docker run --rm --device /dev/net/tun --cap-add NET_ADMIN -ti -p 127.0.0.1:1080:1080 -p 127.0.0.1:8888:8888 -e EC_VER=7.6.3 -e CLI_OPTS="-d vpnaddress -u username -p password" hagb/docker-easyconnect:cli
```

The `--device /dev/net/tun` and `--cap-add NET_ADMIN` flags give the container the network capabilities it needs to create a VPN tunnel. The `EC_VER` variable selects the EasyConnect version; the README notes that version 7.6.7 and 7.6.3 are the two options for the CLI tag. After the container starts, SOCKS5 is available at `127.0.0.1:1080` and the HTTP proxy at `127.0.0.1:8888` on the host.

## Starting the GUI Container and Connecting via VNC

The GUI version adds a VNC server on port 5901 and mounts a data directory to persist VPN credentials between sessions:

```bash
docker run --rm --device /dev/net/tun --cap-add NET_ADMIN -ti -e PASSWORD=xxxx -e URLWIN=1 -v $HOME/.ecdata:/root -p 127.0.0.1:5901:5901 -p 127.0.0.1:1080:1080 -p 127.0.0.1:8888:8888 hagb/docker-easyconnect:7.6.7
```

Connect a VNC client to `127.0.0.1:5901` with the password set in `PASSWORD`. The EasyConnect login window appears in the VNC session. The README notes that arm64 and mips64el builds require adding `-e DISABLE_PKG_VERSION_XML=1` to the command. A Docker Compose file is also included in the repository and uses the same image and port configuration.

## aTrust Support and Available Image Tags

Sangfor's newer aTrust client is supported via a separate image: `hagb/docker-atrust`. The launch command mirrors the EasyConnect GUI command but adds port 54631 and a sysctl flag for local routing. The README documents that aTrust's web-based login can be handled by opening the URL in a browser on the host, since the container mounts the VPN network interface the host can reach. For fully automated login and session keepalive, the README points to an external project `kenvix/aTrustLogin`. The EasyConnect images are tagged as: `latest` (7.6.7 with VNC), `cli` (multi-version headless), `vncless` (7.6.7 without VNC server), `7.6.3` (VNC), `vncless-7.6.3`, `7.6.7` (VNC), and `vncless-7.6.7`. Pulling directly from Docker Hub:

```bash
docker pull hagb/docker-easyconnect:TAG
```

## Limitations: Proprietary Software, Maintenance Status, and Architecture Gaps

The EasyConnect and aTrust client packages inside the container are proprietary software from Sangfor. Their copyright belongs to Sangfor, and the README includes an explicit note not to misuse the project. The container wrapper scripts are licensed under the WTFPL, but that licence does not extend to the EasyConnect binaries inside the image. This means using the container depends on the continued availability of the official Sangfor Linux deb packages. The last push to the repository was on 2026-03-11, which is more than six months before this article. The README includes an open call for new maintainers in issue 275, suggesting that the current contributor base has reduced. The CLI version is limited to amd64, so ARM-based developer machines (such as Apple Silicon Macs) that want CLI mode need to handle architecture translation or use a separate setup. The aTrust chromium variant, documented in the build instructions, must be built locally and is not available as a pre-built image.

## Comparison to Installing EasyConnect Natively

The native EasyConnect Linux client routes all network traffic through the VPN gateway by modifying the host's routing table. Removing it cleanly after use can require manual network configuration. docker-easyconnect scopes the VPN traffic to the proxy endpoints on ports 1080 and 8888, so the host's default route is unaffected. Applications that do not configure the proxy continue routing without VPN. This selective routing model is the primary reason developers at academic institutions use docker-easyconnect: it avoids the full network takeover that the native client performs. The trade-off is that any application that does not support SOCKS5 or HTTP proxy configuration cannot route through the VPN via this container. An IP forwarding (gateway) mode is also documented in `doc/usage.md`, which can route traffic from other devices, but that mode requires additional network configuration on the host.

## Conclusion

docker-easyconnect is useful for developers at institutions that mandate EasyConnect or aTrust for network access but who want to avoid installing the native client on their workstation and routing all traffic through it. The container approach lets them connect only the traffic that needs the VPN via the SOCKS5 or HTTP proxy, while the rest of the system routes normally. The project is not affiliated with Sangfor and relies on the official Linux deb packages, so any change in those packages can break the container. The last push was on 2026-03-11 and the README explicitly recruits maintainers, which means issues may go unaddressed for extended periods. Users running arm64 or mips64el architectures must add the `-e DISABLE_PKG_VERSION_XML=1` flag, as documented in the README.

## FAQ

### Does docker-easyconnect support ARM processors such as Apple Silicon?

The GUI image supports arm64, amd64, and mips64el architectures. The CLI image supports amd64 only. For arm64 GUI runs, the README requires adding -e DISABLE_PKG_VERSION_XML=1 to the docker run command.

### Which EasyConnect versions does docker-easyconnect support?

The CLI tag supports versions 7.6.3, 7.6.7, and 7.6.8 selected via the EC_VER environment variable. Separate image tags are available for 7.6.3 and 7.6.7 GUI versions, along with vncless variants of each.

### Does docker-easyconnect route all host traffic through the VPN?

No. By default it exposes only SOCKS5 on port 1080 and HTTP proxy on port 8888. Only applications that configure those proxies route traffic through the VPN. An IP forward gateway mode is documented separately in doc/usage.md for routing traffic from other devices.

## Sources

- [docker-easyconnect/docker-easyconnect on GitHub](https://github.com/docker-easyconnect/docker-easyconnect)
- [Issues](https://github.com/docker-easyconnect/docker-easyconnect/issues)
- [License: WTFPL](https://github.com/docker-easyconnect/docker-easyconnect/blob/master/LICENSE)
- [README](https://github.com/docker-easyconnect/docker-easyconnect/blob/master/README.md)

---

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