Skip to main content

Multi-Instance

Runix can run multiple copies of a process with a single configuration entry.

Configuration​

processes:
  api:
    entrypoint: ./cmd/api
    instances: 3

Or via CLI:

runix start --name api --instances 3 -- ./cmd/api

Naming Convention​

When instances > 1, each copy gets a numeric suffix:

InstanceName
1api-1
2api-2
3api-3

Each instance is an independent process with its own:

  • Internal ID (UUID)
  • Numeric ID
  • PID
  • Log directory (~/.runix/apps/api-1/, ~/.runix/apps/api-2/, etc.)
  • Restart counter
  • State machine

Default​

When instances is not specified, it defaults to 1 — a single instance with the name as-is (no suffix).

Use Cases​

  • Horizontal scaling — Run N worker processes to handle load
  • Zero-downtime reload — Combine with rolling reload to update instances one at a time
  • Testing — Run multiple instances to test load balancing

Rolling Reload with Multi-Instance​

# Reload all API instances one at a time
runix reload api --rolling --batch-size 1 --wait-ready

The rolling reload processes instances in order: api-1, api-2, api-3.

What's Next​