MEHS Core

Everything you need to use MEHS

Start with the client or server guide, then explore configuration, platform integration, network behavior, and the complete protocol reference. All guides are available here.

Search all guides by topic, option, or error.

Getting started & configuration

Platform & application integration

Network & protocol reference

Ready-to-edit configuration files

Client JSON example / Server JSON example / TLS fingerprint example. Replace placeholder credentials before deployment.

Latest release

Client and server packages from the most recently published release. Use matching releases on both ends and verify archives with the attached checksums.

What MEHS provides

MEHS connects applications on a client device to a configured MEHS server. The client handles authentication, transport setup, local traffic entry points, connection recovery, and reporting status to its host. The server applies its access and transport policies and makes outbound connections for authorized flows.

Transports and traffic modes

In proxy mode, SOCKS5 TCP and HTTP CONNECT carry TCP traffic. SOCKS5 UDP ASSOCIATE is optional and must be enabled for applications that need UDP. In TUN mode, the client accepts IP traffic from the virtual interface and supports TCP, UDP, and DNS flows.

Run the client

Download the client package for the target platform from the MEHS releases page. Obtain a client ID, secret, and server certificate trust file from the server administrator. Keep the client secret out of shell history, process arguments, logs, and support reports.

Local proxy mode

Set the secret in the environment, then start the client with the control endpoint and local listener addresses:

export MEHS_CLIENT_SECRET='your-client-secret'
mehs --control vpn.example.com:8443 --client-id laptop \
  --ca-file ca.pem --transport auto \
  --socks-bind 127.0.0.1:1080 --http-bind 127.0.0.1:8080 \
  --remote-dns

Point an application at the SOCKS5 or HTTP proxy. For example, with curl:

curl --socks5-hostname 127.0.0.1:1080 https://example.com/

Add --udp-associate for SOCKS5 applications that use UDP, such as calls or games. Remote DNS is optional; when enabled, proxied destination names are resolved by the server. The client's own control and data endpoints are still resolved locally.

TUN mode

Run as root or administrator and provide LAN exclusions appropriate for your network:

sudo -E mehs --control vpn.example.com:8443 --client-id laptop \
  --ca-file ca.pem --transport auto --mode tun \
  --tun-exclude 192.168.0.0/16 \
  --tun-exclude 10.0.0.0/8 \
  --tun-exclude 172.16.0.0/12

By default, TUN mode routes all IPv4 and IPv6 traffic through the tunnel. Use --tun-route CIDR to select prefixes, --tun-exclude CIDR to leave prefixes on the normal network, and --tun-no-routes when the host manages routes. The control/data server endpoints must remain reachable outside the tunnel. On Windows, place the matching-architecture wintun.dll next to mehs.exe.

Configuration essentials

Use a schema-versioned client JSON file with --session-config PATH. Schema version 1 is strict: unknown fields are rejected, and configuration is validated at startup. Command-line values can override the corresponding session settings. Configuration is read at startup; disconnect and reconnect to apply static changes.

Server policy takes precedence over client transport and connection-pool requests. The client applies policy corrections or rejects disallowed settings rather than assuming a requested value was accepted. Start with one TCP and one QUIC candidate; increasing pool sizes increases resource use and does not guarantee faster performance.

Download the client configuration example and consult the complete configuration reference for defaults, bounds, profiles, and all accepted fields.

Prepare a MEHS server

The reference server package targets Debian 13 Linux x86_64. Start from the server example configuration, set the TLS certificate and private-key paths, replace every sample client credential, and choose which transports the server will permit.

sudo install -o root -g root -m 600 mehs-server.json /etc/mehs/server.json
sudo MEHS_SERVER_CONFIG=/etc/mehs/server.json /usr/local/bin/mehs-server

The example configuration is a starting point, not a production-ready deployment. See the server administration guide and the server configuration example.

Integrate with an application

The client package includes a C-compatible API and platform libraries. The runtime entry point accepts the same command-line options as the standalone client, starts asynchronously, and returns a handle for status polling and shutdown. Pass credentials through the dedicated secret parameter rather than embedding them in the argument list.

Status states include starting, running, reconnecting, stopped, and failed. Treat failed as terminal: display the secret-free error, stop the handle, correct the configuration or network issue, then start a new runtime. Poll at a modest interval (about once per second), and always stop the runtime during application shutdown.

Status, recovery, and troubleshooting

• Proxy does not connect: confirm the client is running, the application points to the correct loopback port, and local firewall rules permit that listener.
• UDP does not pass in proxy mode: enable --udp-associate and ensure the application uses SOCKS5 UDP. HTTP CONNECT carries TCP only.
• Names fail to resolve: enable --remote-dns for proxied destination names if the server supports domain destinations. This does not change local name resolution for the server endpoints.
• TUN traffic stalls: verify elevated permissions, interface setup, routes, LAN exclusions, and that no other VPN is managing the default route. Keep the MEHS server endpoint on the physical network path.
• QUIC fails: verify the server's QUIC listener and UDP firewall path, or select --transport tcp.

Platform support

Platform availability and verification differ by feature. Check the support matrix before committing to a deployment target, especially for device-wide tunneling and mobile integrations.

Linux server packages target Debian 13 x86_64. Exact feature verification and release compatibility details are maintained in the support matrix. Use the same release for the client and server.

Reference guides and downloads