Skip to main content
Machines are the physical or virtual servers that make up your Uncloud cluster. Each machine runs the uncloudd daemon and participates in the distributed cluster state.

​
Adding machines

Add a new machine to your existing cluster using uc machine add: 
uc machine add [email protected]
This command installs Docker and the Uncloud daemon on the target machine, generates WireGuard keys, allocates a dedicated subnet for the machine and its containers, and adds it to your cluster.

​
SSH connection methods

Uncloud supports two ways to connect to machines: 
# Built-in SSH library (default)
uc machine add [email protected]
uc machine add ssh://[email protected]

# System SSH command (supports ProxyJump and SSH config)
uc machine add ssh+cli://[email protected]
The ssh+cli:// scheme uses your system’s SSH client, which is useful when you need features like ProxyJump for bastion hosts or specific SSH configuration.

​
Common options

Specify a custom name: 
uc machine add [email protected] --name web-server-1
Machine names help you identify machines in commands and logs. If not specified, Uncloud generates a random name. Use a custom SSH key: 
uc machine add [email protected] --ssh-key ~/.ssh/production_key
By default, Uncloud looks for ~/.ssh/id_rsa or uses your SSH agent. Set the public IP address: 
uc machine add [email protected] --public-ip 203.0.113.10
Uncloud tries to auto-detect the public IP, but you can override it for ingress configuration. Use --public-ip none or --public-ip '' to disable ingress on a machine. Skip Caddy deployment: 
uc machine add [email protected] --no-caddy
By default, Uncloud deploys a Caddy reverse proxy container to new machines. Use this flag if you want to manage Caddy separately. Skip installation: 
uc machine add [email protected] --no-install
Use this flag if Docker and the Uncloud daemon are already installed and running on the machine. Install a specific version: 
uc machine add [email protected] --version v0.1.0
By default, Uncloud installs the latest version.

​
Listing machines

View all machines in your cluster: 
uc machine ls
Example output: 
NAME             STATE   ADDRESS         PUBLIC IP        WIREGUARD ENDPOINTS                     MACHINE ID
oracle-vm        Up      10.210.0.1/24   152.67.101.197   10.0.0.95:51820, 152.67.101.197:51820   abc123
hetzner-server   Up      10.210.1.1/24   5.223.45.199     5.223.45.199:51820                      def456
The output shows:
  • NAME: Machine name
  • STATE: Current state (Up, Down, etc.)
  • ADDRESS: The machine’s WireGuard IP and subnet
  • PUBLIC IP: Public IP for ingress (if configured)
  • WIREGUARD ENDPOINTS: Network addresses where other machines can reach this machine
  • MACHINE ID: Unique identifier

​
Updating machines

Update machine configuration using uc machine update:

​
Rename a machine

uc machine update machine1 --name web-server

​
Change the public IP

uc machine update machine1 --public-ip 203.0.113.10
Remove the public IP: 
uc machine update machine1 --public-ip none

​
Update WireGuard endpoints

When a machine’s network configuration changes, you can update its WireGuard endpoints: 
uc machine update machine1 --endpoint 203.0.113.10:51820
Specify multiple endpoints: 
uc machine update machine1 --endpoint 203.0.113.10 --endpoint 192.168.1.5
Endpoints can be specified as:
  • IP - Uses default WireGuard port 51820
  • IP:PORT - Explicit port
  • IPv6 or [IPv6]:PORT - IPv6 addresses

​
Update multiple properties

You can update multiple properties in a single command: 
uc machine update machine1 --name web-server --public-ip 203.0.113.10 --endpoint 203.0.113.10

​
Removing machines

Remove a machine from your cluster: 
uc machine rm machine1
This command:
  1. Stops and removes all service containers on the machine
  2. Removes the machine from the cluster state
  3. Resets the machine to its pre-initialized state (removes WireGuard config, Docker network, etc.)
  4. Removes the connection from your Uncloud config file
The command prompts for confirmation before making changes. You can skip the prompt: 
uc machine rm machine1 --yes

​
Remove without resetting

If you want to remove a machine from the cluster but keep containers and data intact: 
uc machine rm machine1 --no-reset
This is useful when a machine is temporarily unreachable or you want to migrate containers manually.
When you run uc machine rm, Uncloud:
  1. Lists all service containers running on the machine
  2. Gracefully stops each container with a timeout
  3. Removes containers and their anonymous volumes
  4. Removes the machine from the distributed cluster state
  5. Calls the machine’s reset API to clean up:
    • WireGuard interface and configuration
    • Docker bridge network
    • Corrosion (distributed database) state
    • Systemd services
  6. Removes the machine’s connection from your local config
If the machine is unreachable, steps 1, 2, 3, and 5 are skipped, but the machine is still removed from the cluster state.
No. If you’re connected to machine1 and try to run uc machine rm machine1, you’ll get an error:
cannot remove the machine you are currently connected to.
Please connect to another machine in the cluster and try again.
Connect to a different machine first:
uc --connect root@other-machine machine rm machine1
The exception is if machine1 is the last machine in the cluster. In that case, removal is allowed.

​
Machine maintenance

​
Updating the Uncloud daemon

To update the Uncloud daemon on a machine:
  1. SSH into the machine
  2. Download and run the installation script:
ssh [email protected]
curl -fsS https://raw.githubusercontent.com/psviderski/uncloud/main/scripts/install.sh | sh
The script detects the existing installation and upgrades it. The daemon is managed by systemd and restarts automatically.

​
Checking daemon status

SSH into a machine and check the daemon: 
ssh [email protected]
sudo systemctl status uncloud
View daemon logs: 
sudo journalctl -u uncloud -f
Check the Corrosion (distributed database) service: 
sudo systemctl status uncloud-corrosion
sudo journalctl -u uncloud-corrosion -f

​
Restarting services

Restart the Uncloud daemon: 
sudo systemctl restart uncloud
Restart Corrosion: 
sudo systemctl restart uncloud-corrosion

​
SSH access patterns

​
Direct connection

Connect to a specific machine for a single command: 
uc --connect [email protected] machine ls

​
Using contexts

Contexts store connection information for your clusters. List available contexts: 
uc context ls
Switch to a different context: 
uc context use production
Once a context is active, all commands use that cluster: 
uc machine ls
uc service ls

​
Custom SSH ports

If your machine uses a non-standard SSH port: 
uc machine add [email protected]:2222

​
Non-root users

Use a non-root user with sudo access: 
uc machine add [email protected]
The user needs passwordless sudo or you’ll be prompted during installation.

​
Machine networking

Each machine gets a unique /24 subnet from the cluster’s network range (default 10.210.0.0/16):
  • First machine: 10.210.0.0/24
  • Second machine: 10.210.1.0/24
  • Third machine: 10.210.2.0/24
  • And so on…
Within each subnet:
  • .1 is the machine’s WireGuard interface IP
  • .2 to .254 are for container IPs
Containers on different machines communicate directly through the WireGuard mesh. No overlay network drivers or complex routing rules needed.

​
Next steps

DNS Management

Configure managed DNS and custom domains

Caddy Proxy

Set up HTTPS ingress with Caddy

Build docs developers (and LLMs) love

Get started for freeTalk to us