Skip to main content
List all service containers running across all machines in the cluster, providing a comprehensive view of your deployed services.

​
Usage

uc ps [flags]

​
Flags

​
-s, --sort
string
default:"service"
Sort containers by service, machine, or health.

​
Output

The command displays a table with:
  • SERVICE - Service name
  • CONTAINER ID - First 12 characters of the container ID
  • CONTAINER NAME - Full container name
  • IMAGE - Container image
  • CREATED - How long ago the container was created
  • STATUS - Container status (color-coded)
  • IP ADDRESS - Cluster IP address
  • MACHINE - Machine hosting the container

​
Examples

​
List all containers

uc ps
Example output: 
SERVICE   CONTAINER ID   CONTAINER NAME   IMAGE            CREATED        STATUS                    IP ADDRESS    MACHINE
web       abc123def456   web-abc123       nginx:latest     2 hours ago    Up 2 hours (healthy)      10.210.0.5    vps1
web       def456ghi789   web-def456       nginx:latest     2 hours ago    Up 2 hours (healthy)      10.210.1.5    vps2
api       ghi789jkl012   api-ghi789       myapp:v2         1 hour ago     Up 1 hour                 10.210.0.6    vps1
db        jkl012mno345   db-jkl012        postgres:16      1 day ago      Up 1 day (healthy)        10.210.0.7    vps1

​
Sort by machine

uc ps -s machine
Groups containers by machine: 
SERVICE   CONTAINER ID   CONTAINER NAME   IMAGE            MACHINE
web       abc123def456   web-abc123       nginx:latest     vps1
api       ghi789jkl012   api-ghi789       myapp:v2         vps1
db        jkl012mno345   db-jkl012        postgres:16      vps1
web       def456ghi789   web-def456       nginx:latest     vps2

​
Sort by health

uc ps -s health
Shows unhealthy containers first: 
SERVICE   STATUS                  CONTAINER ID   MACHINE
api       Up 10s (unhealthy)      ghi789jkl012   vps1
web       Up 2 hours (starting)   abc123def456   vps1
web       Up 2 hours (healthy)    def456ghi789   vps2
db        Up 1 day (healthy)      jkl012mno345   vps1

​
Status Colors

Container status is color-coded:
  • Green - Healthy
  • Red - Unhealthy, dead, or OOM killed
  • Yellow - Starting, stopped, or other non-critical states
  • White - Running (no health check)

​
Understanding the Output

​
Container Status

Common statuses:
  • Up X hours - Running normally
  • Up X hours (healthy) - Running and passing health checks
  • Up X hours (starting) - Running but health checks haven’t passed yet
  • Up X hours (unhealthy) - Running but failing health checks
  • Exited (0) - Stopped successfully
  • Exited (1) - Stopped with error
  • Restarting - Being restarted

​
IP Address

The cluster-internal IP address. Containers can communicate directly using these IPs or via service names.

​
Container Distribution

See how replicas are distributed across machines: 
uc ps | grep web
Output: 
web   abc123   web-abc123   nginx:latest   vps1
web   def456   web-def456   nginx:latest   vps2
web   ghi789   web-ghi789   nginx:latest   vps3
Shows web service has containers on vps1, vps2, and vps3.

​
Use Cases

​
Monitor Deployments

After deploying, check that containers are running: 
uc deploy
uc ps

​
Debug Issues

Find unhealthy containers: 
uc ps -s health | grep unhealthy

​
Check Distribution

Verify containers are spread across machines: 
uc ps -s machine

​
Get Container IDs

Find a container ID for uc exec: 
uc ps | grep web
uc exec --container abc123 web bash

​
Verify Scaling

After scaling, confirm replica count: 
uc service scale web 5
uc ps | grep web | wc -l
# Should show 5

​
Filtering Output

Use standard Unix tools to filter:

​
Show only one service

uc ps | grep web

​
Show containers on one machine

uc ps | grep vps1

​
Count containers per service

uc ps | grep web | wc -l

​
Find specific container

uc ps | grep abc123

Build docs developers (and LLMs) love

Get started for freeTalk to us