Skip to content
NexployPublic

About

Outbound-only Docker agent for Nexploy — bridges a remote Docker daemon over a WebSocket tunnel, no exposed socket, no inbound port.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Nexploy agent

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.

How it works

agent (target host) --wss outbound--> nexploy --> docker-api
        |                                            |
  /var/run/docker.sock <---- multiplexed channels ---+
  1. The agent authenticates with its token during the WebSocket upgrade.
  2. Nexploy verifies the token, marks the environment online and proxies the socket to docker-api.
  3. docker-api exposes 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.

Protocol package

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.

Install

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:latest

Or with the provided docker-compose.yml:

cp .env.example .env   # fill in NEXPLOY_URL and NEXPLOY_AGENT_TOKEN
docker compose up -d

Configuration

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

Development

pnpm install
pnpm dev
pnpm typecheck

License

GPL-3.0

About

Outbound-only Docker agent for Nexploy — bridges a remote Docker daemon over a WebSocket tunnel, no exposed socket, no inbound port.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages