Remote build runner for Nexploy. Install it on a spare machine, point it at your Nexploy
server, and image builds move off your production host: the runner clones the repository, builds the Docker image and
pushes it to your registry, while production only ever does a docker pull.
- Outbound-only. The runner dials Nexploy over WebSocket. No inbound port, no Docker socket exposed on the network, works behind NAT.
- Multi-server. One runner process talks to one Nexploy server; run several containers side by side to serve several servers, or several runners against one server for parallelism.
- Docker-native install. One container, one Docker socket mount.
┌────────────────────────┐ ┌──────────────────────────┐
│ Nexploy (prod host) │ │ Build host (this repo) │
│ │ wss:// (outbound) │ │
│ pipeline orchestrator │ ◄────────────────────► │ build-runner container │
│ runner gateway │ jobs, logs, results │ git clone │
│ │ │ docker build │
└───────────┬────────────┘ │ docker push │
│ └────────────┬─────────────┘
│ docker pull │ push
▼ ▼
production containers ◄─────────────────────────── container registry
The heavy work (git checkout, docker build, layer compression, registry upload) happens on the build host. The
production host stays responsive: it only pulls the finished image.
docker run -d \
--name nexploy-build-runner \
--restart unless-stopped \
-e NEXPLOY_URL=https://nexploy.example.com \
-e NEXPLOY_RUNNER_TOKEN=nxr_xxxxxxxxxxxxxxxxxxxxx \
-e NEXPLOY_RUNNER_NAME=build-runner-1 \
-e NEXPLOY_RUNNER_CONCURRENCY=2 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v nexploy-runner-workspace:/workspace \
nexploy/build-runner:latestcp .env.example .env # fill in NEXPLOY_URL and NEXPLOY_RUNNER_TOKEN
docker compose up -d
docker compose logs -f build-runnerThe bundled docker-compose.yml mounts the Docker socket, keeps the workspace on a named volume, and binds the health
endpoint to 127.0.0.1:9090 only.
docker build -t nexploy/build-runner:local .NEXPLOY_RUNNER_TOKEN is the runner token issued by the Nexploy server. The server side of this protocol — runner
registration, the /api/ws/runner gateway and job dispatch — is specified in PROTOCOL.md and is not
part of this repository.
| Variable | Default | Description |
|---|---|---|
NEXPLOY_URL |
required | Base URL of the Nexploy server, e.g. https://nexploy.example.com. A path prefix is preserved. |
NEXPLOY_RUNNER_TOKEN |
required | Runner token issued by Nexploy (min. 16 characters). |
NEXPLOY_RUNNER_NAME |
container hostname | Name displayed in the Nexploy UI. |
NEXPLOY_RUNNER_LABELS |
empty | Comma-separated labels used by Nexploy to target this runner, e.g. arm64,gpu. |
NEXPLOY_RUNNER_CONCURRENCY |
2 |
Maximum number of builds running at once. Jobs beyond this are rejected so the server can reroute them. |
NEXPLOY_RUNNER_WORK_DIR |
/workspace |
Where clones live. One directory per repository and job, removed after each build. |
NEXPLOY_RUNNER_JOB_TIMEOUT_MS |
3600000 |
Hard ceiling per job. The server may send a shorter timeout per job. |
NEXPLOY_RUNNER_KEEP_WORKDIR |
false |
Keep the clone after the build. Debugging only — clones contain repository source and .env material. |
NEXPLOY_RUNNER_PRUNE_AFTER_BUILD |
true |
Prune dangling images after each build to keep the build host's disk in check. |
NEXPLOY_RUNNER_ALLOW_INSECURE |
false |
Allow a plain-HTTP NEXPLOY_URL on a remote host. Off by default because the token and registry credentials cross the wire. |
NEXPLOY_RUNNER_TLS_REJECT_UNAUTHORIZED |
true |
Set to false only for a Nexploy server behind a private CA you cannot install. |
NEXPLOY_RUNNER_HEALTH_PORT |
9090 |
Health endpoint port. 0 disables it. |
DOCKER_SOCKET_PATH |
/var/run/docker.sock |
Docker socket used for builds. |
DOCKER_HOST |
unset | Use a TCP daemon instead of the socket, e.g. tcp://127.0.0.1:2375. |
LOG_LEVEL |
info |
fatal, error, warn, info, debug, trace. |
GET /healthz— process is alive (always200while the runner runs).GET /readyz—200when registered with Nexploy,503while reconnecting.
Both return the current state as JSON:
{ "connected": true, "runnerId": "rnr_...", "activeJobs": 1, "maxConcurrency": 2, "draining": false }- Clone — shallow clone of the branch, optional commit checkout and submodules. Credentials come from Nexploy per job and are never written to disk; if the token expired mid-flight the runner asks Nexploy for a fresh one and retries once.
- Build —
docker buildagainst the local daemon with the build args, labels, target stage, platform and cache sources sent by Nexploy..dockerignorein the build context is honoured, so oversized contexts never get packed. - Push — tags and pushes to the registry Nexploy selected, reporting the resulting digest.
- Cleanup — workspace removed, the local copy of the pushed image removed, dangling images pruned.
Every log line streams back to Nexploy in near real time and shows up in the normal build log UI. Cancelling a build in Nexploy aborts the clone, the build and the push on the runner.
If a job carries no registry, the image stays on the build host and the runner says so in the log — that combination is only useful when the build host is the deployment target.
- Disk. Builds are disk-hungry: clones, layer cache and pushed images all live on the build host. Give
/workspaceand/var/lib/dockerreal room, and keepNEXPLOY_RUNNER_PRUNE_AFTER_BUILDon. - Docker socket access is root-equivalent on the build host. Run runners on machines dedicated to building, not next to production workloads you care about.
- Restarts. On shutdown the runner stops accepting jobs and drains in-flight builds for up to 5 minutes before cancelling them. Messages produced while disconnected are buffered and replayed on reconnect, so a short network blip does not lose a build result.
- Multiple servers. Run one container per Nexploy server, each with its own token, name and workspace volume.
pnpm install
pnpm dev # watch mode against a local Nexploy
pnpm test # unit tests
pnpm typecheck
pnpm check # biome format + lint
pnpm buildThe wire format between the runner and Nexploy — and everything the server side must implement — is specified in
PROTOCOL.md.
GPL-3.0