Bus Services

Examples you can adapt.

Use these examples to understand the shape of a Services workflow before adapting it to your project. Keep secrets in .env or a credential provider, not in the public stack file.

Plan a repository stack

An application repository can keep its service stack in the repository root services.yml and the profile tree in profiles/. Start by validating and planning all declared services.

bus services stack validate --all
bus services stack plan --all

Start only the default services

default_services lets the stack define a smaller everyday startup set. Use --all only when you want every service in the file.

bus services up
bus services list
bus services down

Start a full local app stack

A larger Services stack can include infrastructure, integration, and gateway groups: PostgreSQL, an Events API, relays, repository services, workers, task services, and the local product API.

bus services up --all
bus services list

Read status without exposing secrets

JSON status is suitable for automation and health checks. It reports service state and log locations while keeping resolved environment values out of the output.

{
  "services": [
    {
      "id": "api",
      "service_kind": "bus.api",
      "runtime_kind": "native",
      "runtime_provider": "bus",
      "status": "running",
      "pid": 12345,
      "log_path": ".bus/services/api.log"
    }
  ],
  "count": 1
}

Use a dedicated state directory

Dedicated environments should keep service state, tokens, logs, and runtime files under an explicit writable path.

bus services up \
  --file /opt/bus/services.yml \
  --profile-dir /opt/bus/profiles \
  --state-dir /var/lib/bus/services \
  --all