Skip to main content
Rename an existing machine while preserving all configuration including network settings, public IP, and cluster membership.

​
Usage

uc machine rename OLD_NAME NEW_NAME

​
Arguments

​
OLD_NAME
string
required
Current name of the machine to rename
​
NEW_NAME
string
required
New name for the machine

​
Description

The rename command changes the name of an existing machine in the cluster. This is useful when you want to improve machine naming for better organization or to follow a new naming convention. The rename operation:
  • Preserves the machine’s network configuration (subnet, WireGuard keys)
  • Maintains the machine’s public IP address
  • Keeps all cluster state and membership intact
  • Updates DNS records and service discovery automatically
  • Does not affect running containers or services
Machine names must be unique within a cluster. The rename will fail if another machine already has the target name.

​
Examples

​
Rename a machine

uc machine rename server-1 production-web-1
Output: 
Machine "server-1" renamed to "production-web-1" (ID: m1a2b3c4d5e6f7g8)

​
Adopt a naming convention

Rename machines to follow a consistent pattern: 
uc machine rename oracle-vm us-west-1
uc machine rename hetzner-server eu-central-1
uc machine rename home-server us-east-home

​
Fix a typo

uc machine rename prodcution-db production-db

​
What Gets Updated

When you rename a machine:
  1. Machine name in cluster state
  2. Service discovery: Other machines learn the new name automatically
  3. Context configuration: Your local Uncloud config updates the machine name
  4. Container labels: Containers keep running without interruption

​
What Doesn’t Change

  • Machine ID (stays the same)
  • IP addresses (both public and mesh network)
  • WireGuard configuration
  • Running containers and services
  • Volume data
  • Network connectivity
If you have hardcoded the old machine name in scripts or automation, you’ll need to update those references manually.

​
Verification

After renaming, verify the change with: 
uc machine ls
The machine should appear with its new name in the list.

Build docs developers (and LLMs) love

Get started for freeTalk to us