Skip to main content
Gracefully stop all containers of one or more services across all machines in the cluster. Stopped services can be restarted with uc service start.

Usage

uc stop SERVICE [SERVICE...] [flags]

Arguments

SERVICE
string[]
required
Names or IDs of services to stop. Can specify multiple services.

Flags

-s, --signal
string
Signal to send to each container’s main process. Can be a signal name (SIGTERM, SIGINT, SIGHUP, etc.) or a number.Default: SIGTERM
-t, --timeout
integer
default:"10"
Seconds to wait for each container to stop gracefully before forcibly killing it with SIGKILL. Use -1 to wait indefinitely.

Examples

Stop a service

uc stop web

Stop multiple services

uc stop web api worker

Stop with custom timeout

Wait 30 seconds before force-killing:
uc stop web -t 30

Stop with custom signal

uc stop web -s SIGINT

Stop and wait indefinitely

Never force-kill, wait forever for graceful shutdown:
uc stop web -t -1

How It Works

  1. Send Signal - Sends the specified signal (default SIGTERM) to each container’s main process
  2. Wait - Waits for the timeout period for the container to exit
  3. Force Kill - If still running after timeout, sends SIGKILL to force termination
All containers across all machines are stopped in parallel.

Output

Stopping service web
✓ Stopped 3 containers

Graceful Shutdown

Most applications handle SIGTERM by:
  • Finishing current requests
  • Closing database connections
  • Saving state
  • Cleaning up resources
The default 10-second timeout is usually enough. Increase it if your application needs more time:
uc stop web -t 30

Custom Signals

Different signals trigger different behaviors:
  • SIGTERM (default) - Request graceful shutdown
  • SIGINT - Interrupt (like Ctrl+C)
  • SIGHUP - Hangup (often triggers reload)
  • SIGKILL - Force kill (not graceful, used automatically after timeout)
Example with SIGINT:
uc stop web -s SIGINT

State Persistence

Stopping a service does NOT remove:
  • Service configuration
  • Container configuration
  • Volumes
  • Network configuration
Everything is preserved so you can restart the service with uc start.

Difference from Remove

  • uc stop - Stops containers, keeps everything else
  • uc service rm - Stops AND removes containers and service configuration
Use uc stop when you want to temporarily stop a service:
uc stop web
# Later...
uc start web
Use uc service rm when you want to completely remove a service:
uc service rm web

Use Cases

Temporary Maintenance

Stop a service during maintenance:
uc stop web
# Perform maintenance...
uc start web

Resource Conservation

Stop unused services to free resources:
uc stop dev-api staging-worker

Database Maintenance

Stop application before database operations:
uc stop api worker
# Backup database...
uc start api worker

Testing

Stop a service to test failure handling:
uc stop api
# Test how your app handles API being down...
uc start api

Build docs developers (and LLMs) love