Dev

sentinel dev runs a small supervisor and a terminal UI for the dev stack you actually use day to day. You declare your services in .sentinel.yml once, and from then on sentinel dev starts them, tails their logs, ingests them, and lets you stop, restart, and inspect a single service without leaving the terminal.

Use sentinel dev when you want one command to bring up multiple long-running processes (a server, a worker, a Compose stack), keep them grouped under one project, and surface failures in the same Sentinel database as the rest of your local triage.

First run

From the repo root:

sentinel dev

If .sentinel.yml does not exist and the terminal is interactive, sentinel dev drops into the init wizard. The wizard:

• looks at the workspace for likely services (Compose files, package scripts, common dev scripts)
• presents each candidate one at a time with Y / e / n (accept, edit, skip)
• lets you add manual services after the auto-detected ones
• writes .sentinel.yml at the repo root

You can also run the wizard explicitly without starting anything:

sentinel dev init

If you are running non-interactively (CI, scripts) and .sentinel.yml is missing, sentinel dev exits with an error pointing you at sentinel dev init.

.sentinel.yml

A minimal config for one Node command service and one Docker Compose service:

version: 1

defaults:
  group: default
  project: my-app
  confirm_before_start: true

services:
  - name: api
    type: command
    path: ./api
    command: npm run dev

  - name: db
    type: compose_service
    path: ./infra
    service: postgres

groups:
  - name: default
    services: [api, db]

  - name: api-only
    services: [api]

Field reference:

Compose services are supervised with docker compose up -d <service> followed by docker compose logs -f <service> in the service path. In normal mode, Sentinel treats that Compose service as part of the supervised session and may run docker compose stop <service> on shutdown. If a Compose service is already running and you want Sentinel to leave it running, use sentinel dev --attach-only.

Day-to-day commands

Inside the TUI

The dev TUI shows a sidebar with services and a log pane on the right. Drag-select still works in the pane (the TUI does not capture the mouse wheel), so you can copy text the normal terminal way.

The metrics strip (toggle with m) shows CPU% and resident memory per service. For command services it walks the process tree from the spawned PID. For compose_service services it walks the container’s main PID. It updates a few times a second; numbers round at the bar level, so don’t read tenths of a percent into them.

Logs, redaction, and the clipboard

Every line a service prints goes through two paths inside sentinel dev:

1. The raw line is sent to the parser and triage engine, the same as sentinel run or sentinel stdin.
2. A copy is appended to the in-memory log buffer that backs the TUI pane.

When --redact is on (the default), the buffered copy is redacted before it is stored. So the TUI pane already shows redacted logs, and the c keybinding ships that same redacted text to the clipboard. If you turn redaction off explicitly (--redact=false), the TUI shows raw bytes and the clipboard receives raw bytes. Bearer tokens, JWTs, AWS keys, and similar patterns are stripped only while redaction is on.

Project scoping in dev

sentinel dev resolves the project name in this order:

1. --project on the CLI, if set
2. defaults.project in .sentinel.yml
3. the workspace directory name, normalized to lowercase with spaces changed to dashes
4. dev, if the workspace name cannot be resolved

That project is what every fingerprint, occurrence, and trace ingested during the session is scoped to. The local web UI’s project dropdown will show it after the first event lands. See Projects for how scoping interacts with sentinel history, sentinel traces, and the UI.

OpenTelemetry inside dev

For each command service, sentinel dev injects the same OTLP variables that sentinel run injects:

• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
• OTEL_EXPORTER_OTLP_ENDPOINT=<local OTLP/HTTP receiver>
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<endpoint>/v1/traces
• OTEL_RESOURCE_ATTRIBUTES is merged with sentinel.session_id and sentinel.project

If your service uses an OTel SDK that respects these env vars, traces show up in sentinel traces and on the issue detail page automatically. Compose services are not instrumented for you. If you want their traces too, set the same env vars in their Compose file.

See OpenTelemetry for the full picture.

How sessions interact

Only one sentinel dev session runs per workspace at a time. The supervisor records its PID and the resolved state in ~/.sentinel/run/<workspace-hash>/state.json. sentinel dev status and sentinel dev stop find that file and act on it.

If a process crashes or you kill -9 the supervisor, the state file may be left behind. Re-running sentinel dev cleans it up. sentinel dev stop will detect a stale state file and tell you so.

Troubleshooting

If something does not behave the way you expect, try:

• sentinel dev doctor to confirm Docker, Compose, and per-service binaries are installed.
• sentinel dev --dry-run to see the resolved plan.
• sentinel dev status --json to inspect the live session.
• sentinel dev stop --force if a graceful stop times out.

For a list of common failure modes (missing config, OTLP port already in use, redaction surprises), see Troubleshooting.