Bridges a remote Docker daemon to a Nexploy instance over a single outbound WebSocket tunnel — no inbound port, no Docker daemon exposed over TCP, no TLS certificates to generate, works behind NAT.
agent (target host) --wss outbound--> nexploy --> docker-api
| |
/var/run/docker.sock <---- multiplexed channels ---+
- The agent authenticates with its token during the WebSocket upgrade.
- Nexploy verifies the token, marks the environment online and proxies the socket to
docker-api. docker-apiexposes a local Unix socket for that environment. Every connection to it opens a channel in the tunnel, which the agent pipes to/var/run/docker.sock.
Because the tunnel carries raw Docker API bytes, everything works unchanged: hijacked streams (exec, attach,
terminals), log streaming, image builds and docker compose.
See PROTOCOL.md for the wire format.
This repository owns the tunnel protocol, and publishes it so the server side never has to duplicate it:
import { MuxSession, AGENT_WS_PATH, decodeAgentSystemInfo } from '@nexploy/agent/protocol';Nexploy imports that subpath to authenticate the tunnel and multiplex the Docker API over it. Any change to the framing, the flow control or the handshake headers is a change to this package, and both sides must move together.
docker run -d \
--name nexploy-agent \
--restart unless-stopped \
-e NEXPLOY_URL=https://nexploy.example.com \
-e NEXPLOY_AGENT_TOKEN=nxa_xxxxxxxxxxxxxxxxxxxxx \
-v /var/run/docker.sock:/var/run/docker.sock \
nexploy/agent:latestOr with the provided docker-compose.yml:
cp .env.example .env # fill in NEXPLOY_URL and NEXPLOY_AGENT_TOKEN
docker compose up -d| Variable | Default | Description |
|---|---|---|
NEXPLOY_URL |
required | Base URL of the Nexploy server |
NEXPLOY_AGENT_TOKEN |
required | Agent token generated by Nexploy (nxa_…) |
DOCKER_SOCKET_PATH |
/var/run/docker.sock |
Docker socket to bridge |
NEXPLOY_AGENT_HEALTH_PORT |
9091 |
Health endpoint port, 0 disables it |
NEXPLOY_INSECURE_SKIP_TLS_VERIFY |
false |
Skip TLS verification of the Nexploy server |
LOG_LEVEL |
info |
pino log level |
pnpm install
pnpm dev
pnpm typecheckGPL-3.0