Nodes & Providers

Preview environments on Nexos don't run on a centralized cloud. They run on nodes — machines contributed by independent providers. This page is for you if you want to run a node, whether to host your own team's previews or to earn credits by selling capacity back to the network.

Not running a node? You can skip this page. The hosted Nexos service already has a pool of nodes — just push your code and get a URL.

What Nodes Are

A node is a server that runs the Nexos agent and contributes compute resources to the network. Each node runs containerd for container management and BuildKit for building Docker images.

Nodes come in two flavors. Shared nodes join the global pool — any user without their own infrastructure can schedule projects onto them, and the operator earns 70% of usage charges. Private nodes are owned by a specific user or team and only run that owner's projects. Each project picks the pool it wants in its settings.

Nodes can be bare-metal servers, virtual machines, or even powerful developer workstations. The minimum requirements are:

Linux (kernel 5.4+)
4 CPU cores
8 GB RAM
50 GB disk space
containerd 1.7+ installed
BuildKit installed

Joining the Network

To add a node to the Nexos network, you need a join token. Generate one from the dashboard under Nodes > Add Node or via the API:

curl -X POST https://api.nexos.dev/api/nodes/join-token \
  -H "Authorization: Bearer <token>"

Then on the server you want to register, download and run the agent:

# Download the agent binary
curl -L https://releases.nexos.dev/agent/latest/nexos-agent -o /usr/local/bin/nexos-agent
chmod +x /usr/local/bin/nexos-agent

# Join the network
nexos-agent join --token <join-token> --api https://api.nexos.dev

The join command registers the node with the control plane, exchanges TLS certificates, and establishes a persistent gRPC connection.

Agent Configuration

The agent is configured via a YAML file at /etc/nexos/agent.yaml:

# /etc/nexos/agent.yaml
api_url: https://api.nexos.dev
grpc_port: 50051

resources:
  # How much of the machine's resources to offer
  cpu_reserved: 1        # Reserve 1 core for the OS
  memory_reserved: 2048  # Reserve 2GB for the OS (in MB)
  disk_reserved: 20480   # Reserve 20GB for the OS (in MB)

containerd:
  socket: /run/containerd/containerd.sock
  namespace: nexos

buildkit:
  address: unix:///run/buildkit/buildkitd.sock

storage:
  data_dir: /var/lib/nexos
  cache_max_size: 10240  # Max image cache in MB

network:
  wireguard:
    enabled: true
    interface: wg-nexos
    listen_port: 51820

Resource Reporting and Heartbeats

The agent sends heartbeat messages to the control plane every 30 seconds via the gRPC bidirectional stream. Each heartbeat includes:

CPU usage — Current utilization and available cores
Memory usage — Used and available RAM
Disk usage — Used and available storage
Running containers — Count of active environments
Network stats — Bandwidth usage and latency

The scheduler uses this data to select the best node for each deployment. It considers available capacity, geographic proximity to the developer, and cache affinity (preferring nodes that have previously built the same project for faster incremental builds).

Node Status Monitoring

Monitor your nodes from the dashboard under the Nodes tab. Each node shows:

Status — Online, offline, or draining
Uptime — Time since the agent started
Resource utilization — CPU, memory, and disk graphs
Active environments — List of running containers
Build history — Recent builds executed on this node

If a node stops sending heartbeats for more than 90 seconds, it is marked as offline. Environments running on offline nodes are automatically rescheduled to healthy nodes.

To gracefully remove a node, put it in drain mode from the dashboard. This prevents new deployments from being scheduled to the node while existing environments continue to run. Once all environments have been migrated or destroyed, you can safely shut down the agent.