Skip to main content
This quickstart guide walks you through creating your first Uncloud cluster and deploying a simple web application. You’ll learn the core concepts and commands needed to manage containerized applications across multiple machines.

​
Prerequisites

Before you begin, you’ll need:
  • A Linux server (cloud VM or bare metal) with SSH access and sudo privileges
  • Ubuntu, Debian, or any systemd-based Linux distribution
  • AMD64 (x86_64) or ARM64 (aarch64) architecture
  • Your local machine (macOS, Linux, or Windows with WSL)
Uncloud installs Docker automatically during machine initialization if it’s not already present.

​
Install the CLI

1

Install Uncloud CLI

Install the uc command-line tool on your local machine.Using Homebrew (macOS/Linux):
brew install psviderski/tap/uncloud
Using curl (macOS/Linux):
curl -fsS https://get.uncloud.run/install.sh | sh
The install script downloads the latest binary and creates a convenient uc shortcut.
2

Verify installation

Confirm the CLI is installed correctly:
uc --version
See the installation guide for more installation methods.

​
Initialize your first machine

1

Initialize the cluster

Initialize your first machine and create a new cluster. Replace root@your-server-ip with your server’s SSH connection string:
uc machine init root@your-server-ip
This command will:
  • SSH into your server
  • Install Docker (if not already installed)
  • Install the uncloudd daemon and Corrosion database
  • Set up WireGuard networking
  • Deploy Caddy reverse proxy for HTTPS
  • Reserve a cluster domain like xuw3xd.cluster.uncloud.run
You can specify a custom machine name with --name:
uc machine init --name my-server [email protected]
2

Wait for initialization

The initialization process takes 1-2 minutes. You’ll see progress messages as each step completes:
✓ Docker installed successfully.
✓ Linux user and group 'uncloud' created.
✓ uncloudd binary installed: /usr/local/bin/uncloudd
✓ Uncloud machine daemon started.
✓ Uncloud installed on the machine successfully! 🎉
3

Verify the machine

List machines in your cluster:
uc machine ls
You should see your machine in the “Up” state with its WireGuard network address.

​
Deploy your first service

Now that you have a working cluster, let’s deploy a simple web application.
1

Deploy from a Docker image

Deploy a container from a Docker image and expose it with HTTPS:
uc run -p app.example.com:8000/https nginx:alpine
This command:
  • Pulls the nginx:alpine image
  • Starts a container on your machine
  • Exposes container port 8000 as HTTPS on app.example.com
  • Automatically configures Caddy for TLS termination
Replace app.example.com with a domain you own.
2

Configure DNS

Create a DNS A record in your DNS provider (Cloudflare, Namecheap, etc.) that points app.example.com to your server’s public IP address.Allow a few minutes for DNS propagation, then visit https://app.example.com in your browser.
3

View running services

List all services in your cluster:
uc ls
You’ll see your service name, image, scale, and endpoints.
Don’t have a custom domain? Uncloud provides free *.cluster.uncloud.run subdomains for testing. Check the output of uc machine init for your cluster domain.

​
Add a second machine

Scale your cluster by adding another machine.
1

Add the machine

Add a second server to your cluster:
uc machine add --name second-server root@second-server-ip
The new machine will:
  • Get provisioned with Uncloud
  • Establish a WireGuard tunnel to your first machine
  • Sync the cluster state via Corrosion
  • Start running Caddy for load balancing
2

Verify both machines

List machines again:
uc machine ls
You should see both machines with their WireGuard network addresses and public IPs.
3

Scale your service

Scale your existing service to run on both machines:
uc scale nginx-alpine 2
Containers will be distributed across your machines automatically. Traffic will load balance between them.

​
Deploy with Docker Compose

For more complex applications, use Docker Compose format.
1

Create a compose.yaml file

Create a compose.yaml file with your service definition:
services:
  web:
    image: nginx:alpine
    environment:
      APP_ENV: production
    x-ports:
      - myapp.example.com:80/https
    deploy:
      replicas: 2

  api:
    image: node:20-alpine
    command: node server.js
    environment:
      DATABASE_URL: postgres://db.internal:5432
    deploy:
      replicas: 3
The x-ports field defines public HTTPS endpoints. The deploy.replicas field sets the number of containers.
2

Deploy the stack

Deploy all services from the compose file:
uc deploy
Uncloud will:
  • Parse your compose file
  • Schedule containers across available machines
  • Set up service discovery (services can reach each other by name)
  • Configure Caddy for public endpoints
  • Perform rolling updates to avoid downtime
3

View service logs

Stream logs from your services:
uc logs web
Logs from all replicas are merged and timestamped.
Services can communicate with each other using internal DNS names like api.internal or db.internal. No need to configure networking manually.

​
Clean up

When you’re done experimenting, clean up your resources.
1

Remove services

Remove a service by name:
uc rm web
uc rm api
2

Remove machines

Remove machines from the cluster:
uc machine rm second-server
3

Uninstall Uncloud

If you want to fully uninstall Uncloud from a machine, SSH into it and run:
uncloud-uninstall
This removes all Uncloud components but leaves Docker installed.

​
Next steps

Now that you’ve deployed your first application, explore more features:

Docker Compose

Learn about Compose file format and extensions

Persistent storage

Run stateful services with volumes

Service discovery

Connect services using internal DNS

CLI reference

Explore all available commands
Uncloud is currently in active development and is not ready for production use. Features may change significantly between releases.

Build docs developers (and LLMs) love

Get started for freeTalk to us