Services

A service is any process you start with a shell command - a dev server, database, background worker, build watcher, or anything else.

Defining a service

Each service belongs to a project. To add one, open the project in the CMDHub popover and click Add Service.

Field	Required	Description
Name	Yes	Display name shown in the popover
Command	Yes	Shell command that starts the process
Working directory	No	Defaults to the project root directory
Port	No	Port the service listens on; used by the reverse proxy

Example service definitions:

Name:    API Server
Command: go run ./cmd/api
Dir:     (project root)
Port:    4000

Name:    Worker
Command: bundle exec sidekiq -c 5
Dir:     (project root)

Environment variables

You can inject environment variables into a service two ways, and they are merged at startup:

Inline key-value pairs - defined directly on the service:

"env": {
  "PORT": "4000",
  "LOG_LEVEL": "debug"
}

.env file - a path relative to the project root:

"envFile": ".env.local"

When both are present, inline values take precedence over values from the file.

Tip

Keep secrets (API keys, database passwords) in a .env file that is gitignored. Use inline variables only for non-sensitive values like port numbers.

Dependencies

Services can declare that they depend on other services. CMDHub uses topological ordering to start dependencies first.

In the UI, add a dependency by selecting services from the Depends on picker. In config.json it looks like:

"dependencies": ["svc-id-of-database", "svc-id-of-redis"]

When you click Start All, CMDHub:

1. Builds a dependency graph across all services in the project.
2. Starts services in order, respecting dependencies.
3. Waits for a dependent service’s health check to pass (if configured) before starting the next tier.

If a dependency crashes, services that depend on it are stopped automatically.

Service lifecycle

stopped → starting → running → unhealthy
                              ↓
                          stopping → stopped
                              ↓
                           crashed

State	Meaning
stopped	Not running
starting	Process launched, health check not yet passing
running	Running and healthy (or no health check configured)
unhealthy	Running but health check is failing
stopping	Received stop signal, waiting for process to exit
crashed	Process exited unexpectedly with a non-zero code

Crash detection and restart

If a service process exits with a non-zero exit code, CMDHub marks it as crashed and displays an alert in the popover. The service does not restart automatically - click the play button to restart it manually.

This is intentional: auto-restart can mask configuration errors. The crash state makes it obvious that something needs attention.

Log output

Click any running service in the popover to open its log panel. Logs are streamed live from stdout and stderr. The log buffer holds the most recent output - scroll up to see earlier lines.