Skip to main content
Initialize a new cluster by setting up a remote machine as the first member. This command creates a new context in your Uncloud config to manage the cluster.

​
Usage

uc machine init [schema://]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

​
-c, --context
string
default:"default"
Name of the new context to be created in the Uncloud config to manage the cluster.
​
--dns-endpoint
string
default:"https://dns.uncloud.run/v1"
API endpoint for the Uncloud DNS service.
​
-n, --name
string
Assign a name to the machine. If not specified, a name will be generated.
​
--network
string
default:"10.210.0.0/16"
IPv4 network CIDR to use for machines and services.
​
--no-caddy
Don’t deploy Caddy reverse proxy service to the machine. You can deploy it later with uc caddy deploy.
​
--no-dns
Don’t reserve a cluster domain in Uncloud DNS. You can reserve it later with uc dns reserve.
​
--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

​
Initialize a cluster with default settings

uc machine init [email protected]

​
Initialize with a custom context and machine name

uc machine init [email protected] -c prod -n vps1

​
Initialize with a non-root user and custom SSH settings

uc machine init [email protected]:2222 -i ~/.ssh/mykey

​
Initialize without Caddy and DNS

You can deploy Caddy with uc caddy deploy and reserve a domain with uc dns reserve later: 
uc machine init [email protected] --no-caddy --no-dns

​
Initialize using system SSH with ProxyJump

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

​
What Happens During Initialization

  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 Setup - Initializes the cluster on the machine
  4. Config Update - Creates a new context in ~/.config/uncloud/config.yaml
  5. DNS Setup - Reserves a *.uncld.dev domain (unless --no-dns is used)
  6. Caddy Deployment - Deploys the Caddy reverse proxy (unless --no-caddy is used)
  7. DNS Records - Updates DNS records to point to the machine’s public IP

​
Output

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

Cluster initialized successfully!
Context 'default' created in /home/user/.config/uncloud/config.yaml

Cluster is ready.

Reserved cluster domain: abc123.uncld.dev

Deploying service caddy
✓ caddy deployment complete

Updated DNS records for abc123.uncld.dev

Build docs developers (and LLMs) love

Get started for freeTalk to us