Skip to main content

Quick Start

This guide walks you from a fresh install to a working DockNimbus setup with nodes ready for workloads.

1. Bootstrap and configure​

Option A: GUI — Open https://<API_HOST>:9443 in your browser, set the admin password, and click Download Config to save nimbus-config.json.

Option B: CLI

# Create the admin user (prints credentials and connection config)
nimbus bootstrap --api-url https://<API_HOST>:8443
# Save the connection_config block as nimbus-config.json

Then configure the CLI:

nimbus configure --from nimbus-config.json

If you're connecting from outside the WireGuard mesh (e.g. your laptop), override the API URL with the public IP:

nimbus configure --from nimbus-config.json --api-url https://<PUBLIC_IP>:8443

You can also configure manually:

nimbus configure \
  --api-url https://<API_HOST>:8443 \
  --access-key <ACCESS_KEY> \
  --secret-key <SECRET_KEY>

The configuration is saved to ~/.nimbus/config.json with the API URL, credentials, and CA certificate embedded.

2. Add nodes​

Network requirements

Before adding nodes, make sure the following ports are open:

  • API server: TCP 8443 (control plane) and UDP 51820 (WireGuard)
  • Each node: UDP 51820 (WireGuard)

Register remote machines via SSH. This generates a join token, deploys the agent, configures WireGuard, and registers the node over the encrypted tunnel:

nimbus node add --ip 192.168.1.10 --user root --key ~/.ssh/id_rsa
nimbus node add --ip 192.168.1.11 --user root --key ~/.ssh/id_rsa

For repeated use or shared SSH settings, create a reusable profile first: nimbus ssh-profile add and then use --profile <name> instead of --user/--key.

If a deploy fails (for example, a wrong or unreachable IP), it cleans up after itself, so you can retry right away. A machine that used to run a DockNimbus control plane can be added too: the join disables its old nimbus-api/nimbus-gui and backs up their files. It does not leave an old Docker Swarm, so run docker swarm leave --force on it first if it still has one.

For nodes where SSH is not available (multi-cloud, NAT), generate a join token and run the agent manually:

# On the operator machine:
nimbus node add --get-token --ip <NODE_PUBLIC_IP>

# On the target node (copy the token from above): 
nimbus-agent --join --token <TOKEN>

If the node cannot be reached via SSH but can reach the API's public IP (e.g. behind NAT), run this command directly on the node. WireGuard will establish the tunnel back to the API once the agent connects:

# Run on the node itself:
sudo nimbus node add --local --ip <API_PUBLIC_IP>

Managing nodes in the UI​

The Nodes page works by selection: tick the nodes you want with the checkboxes (or Select all), and the toolbar above the table acts on them. Every action lives there, so there is one place to look.

Actions that work on any number of nodes — Update agent, OS update, Reboot, Check updates — show how many of the selected nodes they apply to, such as Update agent (2) when only two are outdated, and are disabled when that count is zero.

Rename, Change IP and Delete act on a single machine, so they are enabled only when exactly one node is selected. Delete still asks you to type the node's name.

Progress for anything you start appears in the activity dock.

3. Verify​

nimbus node list

You should see your nodes with status ready:

ID              NAME  IP             STATUS  ROLE  AGENT  CPU        MEMORY
node-xxxxxxxx         192.168.1.10   ready   -     v0.2   4000/4000  7802MB/7802MB
node-yyyyyyyy         192.168.1.11   ready   -     v0.2   4000/4000  7802MB/7802MB

Next steps​