Skip to main content
Add a new machine to an existing Uncloud cluster. The machine will join the cluster’s WireGuard mesh network and become available for scheduling service containers.

​
Usage

uc machine add [USER@]HOST[:PORT] [flags]

​
Connection Methods

You can connect to the remote machine using different schemas:
  • ssh://user@host - Use built-in SSH library (default, no prefix required)
  • ssh+cli://user@host - Use system SSH command (supports ProxyJump, SSH config)

​
Flags

​
-n, --name
string
Assign a name to the machine. If not specified, a name will be generated.
​
--no-caddy
Don’t deploy Caddy reverse proxy service to the machine.
​
--no-install
Skip installation of Docker, Uncloud daemon, and dependencies on the machine. Assumes they’re already installed and running.
​
--public-ip
string
default:"auto"
Public IP address of the machine for ingress configuration.
  • auto - Automatic detection
  • none or blank - Disable ingress on this machine
  • IP address - Specify an explicit IP
​
-i, --ssh-key
string
Path to SSH private key for remote login (if not already added to SSH agent).Default: ~/.ssh/id_rsa
​
--version
string
default:"latest"
Version of the Uncloud daemon to install on the machine.
​
-y, --yes
Auto-confirm prompts (for example, resetting an already initialized machine). Should be explicitly set when running non-interactively, like in CI/CD pipelines.Can also be set with the UNCLOUD_AUTO_CONFIRM environment variable.

​
Examples

​
Add a machine to the cluster

uc machine add [email protected]

​
Add a machine with a custom name

uc machine add [email protected] -n worker1

​
Add a machine without Caddy

Useful if you only want to run backend services on this machine: 
uc machine add [email protected] --no-caddy

​
Add a machine using system SSH

This is useful when you need to use SSH config features: 
uc machine add ssh+cli://[email protected]

​
Add a machine with no public IP

For machines that won’t serve public traffic: 
uc machine add [email protected] --public-ip none

​
What Happens When Adding a Machine

  1. SSH Connection - Connects to the remote machine via SSH
  2. Installation - Installs Docker and the Uncloud daemon (unless --no-install is used)
  3. Cluster Join - Joins the machine to the existing cluster
  4. WireGuard Setup - Configures WireGuard mesh networking with other machines
  5. Caddy Deployment - Deploys Caddy if the service already exists (unless --no-caddy is used)
  6. DNS Update - Updates DNS records to include the new machine’s public IP

​
Output

Installing Uncloud on [email protected]...
✓ Installed Docker
✓ Installed Uncloud daemon
✓ Started Uncloud daemon

Machine joined the cluster.

caddy deployment plan:
+ Create container on machine worker1

Deploying service caddy (replicated mode)
✓ caddy deployment complete

Updated DNS records for abc123.uncld.dev

Build docs developers (and LLMs) love

Get started for freeTalk to us