Skip to main content
Run a new service from a container image. This is the imperative way to deploy services, similar to docker run but for the entire cluster.

​
Usage

uc run IMAGE [COMMAND...] [flags]

​
Arguments

​
IMAGE
string
required
Container image to run (for example, nginx:latest or postgres:16).
​
COMMAND
string[]
Override the default command of the container image.

​
Flags

​
--caddyfile
string
Path to a custom Caddy config (Caddyfile) for the service. Cannot be used together with non-@host published ports.
​
--cpu
float
Maximum number of CPU cores a service container can use. Fractional values are allowed, like 0.5 for half a core or 2.25 for two and a quarter cores.
​
--entrypoint
string
Overwrite the default ENTRYPOINT of the image. Pass an empty string "" to reset it.
​
-e, --env
string[]
Set an environment variable for service containers. Can be specified multiple times.Format: VAR=value or just VAR to use the value from the local environment.
​
--mode
string
default:"replicated"
Replication mode of the service:
  • replicated - A specified number of containers across the machines
  • global - One container on every machine
​
-m, --machine
string[]
Placement constraint by machine names, limiting which machines the service can run on. Can be specified multiple times or as a comma-separated list. Default is any suitable machine.
​
--memory
string
Maximum amount of memory a service container can use. Value is a positive integer with optional unit suffix (b, k, m, g). Default unit is bytes if no suffix specified.Examples: 1073741824, 1024m, 1g (all equal 1 gibibyte)
​
-n, --name
string
Assign a name to the service. A random name is generated if not specified.
​
--privileged
Give extended privileges to service containers. This is a security risk and should be used with caution.
​
-p, --publish
string[]
Publish a service port to make it accessible outside the cluster. Can be specified multiple times.Format: [hostname:]container_port[/protocol] or [host_ip:]host_port:container_port[/protocol]@hostSupported protocols: tcp, udp, http, https (default is tcp)If a hostname for http(s) port is not specified and a cluster domain is reserved, service-name.cluster-domain will be used.
​
--pull
string
default:"missing"
Pull image from the registry before running service containers.Options: always, missing, never
​
--replicas
integer
default:"1"
Number of containers to run for the service. Only valid for a replicated service.
​
-u, --user
string
User name or UID and optionally group name or GID used for running the command inside service containers.Format: USER[:GROUP] or UID[:GID]. If not specified, the user is set to the default user of the image.
​
-v, --volume
string[]
Mount a data volume or host path into service containers. Service containers will be scheduled on the machine(s) where the volume is located. Can be specified multiple times.Format: volume_name:/container/path[:ro|volume-nocopy] or /host/path:/container/path[:ro]

​
Examples

​
Run a simple web server

uc run nginx:latest -p 80/https

​
Run with a custom hostname

uc run nginx:latest -p myapp.example.com:80/https

​
Run with environment variables

uc run postgres:16 -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=myapp

​
Run with resource limits

uc run myapp:latest --cpu 2 --memory 4g

​
Run with a named volume

uc run postgres:16 -v postgres-data:/var/lib/postgresql/data -e POSTGRES_PASSWORD=secret

​
Run in global mode

One container on every machine: 
uc run caddy:latest --mode global -p 80/http -p 443/https

​
Run with multiple replicas

uc run myapp:latest --replicas 3 -p 8080/https

​
Run on specific machines

uc run myapp:latest -m machine1,machine2

​
Run with host path mount

uc run myapp:latest -v /data/uploads:/app/uploads

​
Run with custom entrypoint

uc run python:3.11 --entrypoint python -v /app:/code python /code/app.py

​
Port Publishing Examples

​
HTTPS with automatic hostname

If you have a cluster domain reserved (like abc123.uncld.dev), this will be accessible at servicename.abc123.uncld.dev: 
uc run myapp:latest -p 8080/https

​
HTTPS with custom hostname

uc run myapp:latest -p app.example.com:8080/https

​
Multiple ports

uc run myapp:latest -p 80/http -p 443/https -p 8080/http

​
Host port binding

Bind container port 53 to host port 53 (UDP): 
uc run dnsmasq:latest -p 53:53/udp@host

​
Volume Mounting Examples

​
Named volume

uc run postgres:16 -v postgres-data:/var/lib/postgresql/data

​
Multiple volumes

uc run myapp:latest -v app-data:/data -v app-logs:/var/log/app

​
Read-only volume

uc run myapp:latest -v config:/etc/myapp:ro

​
Host directory bind mount

uc run myapp:latest -v /host/data:/container/data

​
Output

Running service myapp (replicated mode)
✓ Created container on machine vps1
✓ Started container myapp-abc123

myapp endpoints:
 • https://myapp.abc123.uncld.dev

Build docs developers (and LLMs) love

Get started for freeTalk to us