Run vxcloud on your own computer
Pull a single container, expose it over HTTPS, and you have the full vxcloud control plane — the same binary we ship on production. No vendor lock-in, no node fee, and your data stays on your hardware. Available on every plan, starting with the 7-day free trial.
$ docker pull vxcloud/vxnode:latest latest: Pulling from vxcloud/vxnode Digest: sha256:e2…b9 Status: Image is up to date $ docker run -d --name vxcloud-vxnode \ -p 8744:8744 -p 8743:8743 \ vxcloud/vxnode:latest 3f9c4b7e21… vxnode listening on :8744 $ vxcli node add --endpoint https://node1.vxcloud.io ✓ node "primary" registered with workspace ✓ tls verified · vxcli ⇄ vxnode handshake ok ✓ ready to deploy
~80 MB
Image size (compressed)
5 min
From pull to first deploy
$0
Node fees, on your hardware
OSS-friendly
No telemetry by default
Why self-host
Your infra, your rules
vxnode is the same image we run in production at prodxcloud. Self-host it when you want full control — switch to managed nodes when you don't.
Data sovereignty
Your source code, build artifacts, secrets, and logs never leave your machine. No third-party data plane.
Zero subscription cost
Run vxnode for free on hardware you already pay for. Pay only when you scale out to managed nodes.
Air-gapped friendly
Designed to run behind firewalls and on-prem. Pin a registry mirror and you are good for fully offline ops.
Same binary as managed
vxnode is the exact image we ship on prodxcloud. Self-hosted parity — no feature-flag downgrade.
Quick install
One container. Two ports. Five minutes.
Copy these two commands. You will have a fully working vxnode listening on localhost when they finish.
docker pull vxcloud/vxnode:latestdocker run -d \
--name vxcloud-vxnode \
--restart unless-stopped \
-p 8744:8744 \
-p 8743:8743 \
-v vxnode-data:/var/lib/vxnode \
-e VXNODE_BIND=0.0.0.0 \
-e VXNODE_DOMAIN=node1.vxcloud.io \
vxcloud/vxnode:latestvxnode now serves http://localhost:8744. Continue below to expose it on the internet and register it with vxcloud.
Walkthrough
From zero to first deploy
The same path used by every prodxcloud production node — only this time you own the box.
Step 01
Install Docker
vxnode ships as a single OCI container. You need Docker Engine 24+ (or Docker Desktop on macOS/Windows). Anything that runs Docker — Linux box, Mac mini, an old laptop, a $4/mo VPS — works.
# Linux (one-liner)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker
# Verify
docker --versionStep 02
Pull and run vxnode
Pull the production image from Docker Hub (vxcloud/vxnode) and run it. It exposes 8744 for the Go/Gin API and 8743 for the admin/secondary channel.
docker pull vxcloud/vxnode:latestdocker run -d \
--name vxcloud-vxnode \
--restart unless-stopped \
-p 8744:8744 \
-p 8743:8743 \
-v vxnode-data:/var/lib/vxnode \
-e VXNODE_BIND=0.0.0.0 \
-e VXNODE_DOMAIN=node1.vxcloud.io \
vxcloud/vxnode:latestStep 03
Install vxcli
The control surface is the vxcli binary — a single statically-linked Go executable that runs anywhere (Linux, macOS, Windows) with no runtime to install. Use it to manage your node, deploy workloads, and stream logs.
# Linux / macOS — static Go binary → ~/.local/bin, no sudo
curl -fsSL https://vxcloud.io/download/cli/install.sh | sh
# Windows (PowerShell):
# irm https://vxcloud.io/download/cli/install.ps1 | iex
# Verify, then sign in
vxcli version
vxcli auth login --deviceStep 04
Expose your node over HTTPS
vxnode talks HTTPS to the rest of the platform. If your machine sits behind NAT or a residential connection, the simplest path is a tunnel — pick whichever you already use. Both give you a managed TLS cert and a public hostname in under a minute, no router config.
# Install cloudflared, then expose vxnode over HTTPS via a free Cloudflare Tunnel.
cloudflared tunnel login
cloudflared tunnel create vxnode
# Map your hostname to the local vxnode port
cloudflared tunnel route dns vxnode node1.vxcloud.io
cloudflared tunnel run --url http://localhost:8744 vxnode
# Cloudflare now serves https://node1.vxcloud.io with a managed TLS cert.80/443 and skip tunnels entirely.Step 05
Register the node in vxcloud
Last step: tell the vxcloud dashboard about your self-hosted node so workloads can be scheduled on it. You can do it from the CLI or from Nodes › Add node.
# Once vxnode is reachable over HTTPS, point vxcli at it and
# register it with your vxcloud workspace.
vxcli node add \
--name primary \
--endpoint https://node1.vxcloud.io \
--port 8744 \
--provider self-hosted
# Or use the dashboard: Nodes › Add node › Self-hosted (BYO)How it fits
Architecture in one diagram
vxnode runs anywhere Docker runs. vxcli on your laptop talks to it over HTTPS, and the vxcloud dashboard reads its public endpoint so your workloads schedule on your hardware.
- No outbound poll — vxnode is reached on its public hostname only.
- Mutual TLS between vxcli and vxnode using a workspace-scoped cert pair.
- State persists in the
/var/lib/vxnodevolume — survives restarts and upgrades.
Exposed ports
8744TCP / HTTPSGo/Gin API — main control plane8743TCP / HTTPSAdmin / secondary (audit + ops)
vxcli (your laptop)
vxcli · static Go binary
HTTPS · Cloudflare / Tailscale
https://node1.vxcloud.io
vxcloud/vxnode:latest
:8744 api · :8743 admin · Go/Gin
vxcloud dashboard
prodxcloud.com / Nodes
Day-2 ops
Logs, restarts, upgrades
vxnode is a single container — operations stay boring on purpose.
# Common ops commands once vxnode is running.
docker logs -f vxcloud-vxnode # follow logs
docker restart vxcloud-vxnode # restart
docker exec -it vxcloud-vxnode sh # shell into the container
# Upgrade to the latest release
docker pull vxcloud/vxnode:latest
docker rm -f vxcloud-vxnode
docker compose up -d # if you used docker-compose
# (existing volumes are preserved)Self-hosted vs Managed
Pick the trade-off that fits
Start free on your hardware. Upgrade to a managed node when you stop wanting to think about TLS, backups, or scheduling.
FAQ
Questions teams ask before self-hosting
Ship your first workload on your own box today
One docker pull, one npm install, one tunnel. No card. No expiry.