Run your services
Run your services
Read this when you want to start, inspect, restart, or stop services in a checkout.
Expanded status and the menu bar show ready in-process Service.make/Service.container services indented beneath their owning process, with ports such as postgres :5432. Child rows have no actions; stop/restart still control the parent. Children are transient and are not persisted. Protocol-v1 listRuns/getRun responses optionally include children: [{ name, ports?: Record<string, number> }] on each service, omitted when empty.
In-process reporters use reportService { runId, service, name, ports?, instanceId? } and retractService { runId, service, name, instanceId? }, both acknowledged with {}. The daemon supplies DEVSESS_INSTANCE_ID alongside DEVSESS_SOCKET, DEVSESS_RUN_ID, and DEVSESS_SERVICE; reports must match that live process instance. Missing, stale, or exited instances are silently ignored. Re-reporting a name replaces its ports without changing row order. Library reports use a 250ms timeout, no retries, and silently tolerate older or unreachable daemons.
Readiness publish and unpublish also accept optional instanceId, sent by the library when available. A mismatched instance is rejected so an old process cannot change its replacement’s readiness. Requests without the field remain supported for older reporters.
Expanded status output includes compact resident memory next to live service PIDs when available. Memory sums RSS across the service’s process group and descendants that left it, counting each PID once. It is sampled on demand and cached for two seconds, never persisted, and omitted when unavailable; a sampling failure does not prevent status reporting. Displayed KB/MB/GB use powers of 1024.
For protocol-v1 clients, stopServices accepts { runId, serviceNames: string[], force?: boolean } and returns the updated run record, just like stopRun. Names must be non-empty, distinct, and exist in the run. listRuns and getRun may include memoryBytes: number on each live service (RSS in bytes); finished services and unavailable samples omit the field. Clients must tolerate its absence, including responses from older daemons.
devsess list [--names] [--config path] [--project name]
devsess start [options] [preset]
devsess status [-a|--all] [--project name]
devsess restart [options] [--service name | --all-services] [preset|run-id]
devsess stop [options] [--service name] [--force] [preset|run-id]
list reads the config and reports presets matched by the current directory, each service command and resolved working directory, and which presets await publication. It does not start the daemon. If the daemon is reachable, it marks active presets as running. Its bare-start summary explains whether start would choose one preset, offer a picker, or fail without a terminal.
list --names prints only selectors accepted by start, one per line: bare preset names for one matched project, or project/preset for multiple projects. It honours --project and --config and never contacts or starts the daemon. Shell completion uses this mode; see devsess docs read completions.
start captures the current environment and starts the selected preset through the detached daemon. It waits for a daemon handshake and acknowledgment, then observes the run for about two seconds and prints readiness publications as they arrive. If a service exits during that window, it prints the exit status, recent output, and an exact tail command; if every service fails, start exits nonzero. Otherwise it prints the run ID and returns to the shell while services continue. The run records the invocation directory.
With awaitPublish: true, start waits for every included service to publish readiness, with no default timeout. After 15 seconds it prints pending services and a tail command for each. If one exits without publishing, start reports its exit status and recent output and exits nonzero without stopping the other services. Ctrl-C stops waiting, not the services; check their progress with devsess status.
Only one active project/preset identity can run at a time. A completed or failed record can be reused only after every service process stops; a failed aggregate state can still have a live service blocking another start.
status reports active runs across projects with short run IDs. Runs under the current directory (or named with --project) show start time, uptime, and each service’s state, PID, exit code, command, and working directory; other projects get a summary line. Published services show ready and their URL or named URLs; other published values appear as compact, truncated JSON. Readiness is persisted with the run and cleared when a service unpublishes or exits. status does not start the daemon; if it is down, it says so. When nothing is running, it shows the latest finished run from this directory (or latest overall) with exit codes and a tail command. One finished run per project, preset, and checkout is retained. -a/--all expands every active run; finished runs are never listed. --project <name> narrows results. For the daemon process itself, see devsess docs read daemon.
restart replaces one or more services in an active run without changing the run ID or interrupting other services. Choose --service <name> (-s) or --all-services; with several services, a terminal offers a picker and non-interactive use lists exact selection commands. It stops selected processes and descendants, appends a restart marker to their logs, and respawns them with the original command, working directory, and environment held in daemon memory. After a daemon restart, stop the run and start again before using restart: the environment is not saved in the registry. Readiness is cleared before respawn. For a service configured to await publication, restart waits for fresh readiness; an exit without publication prints recent output and a tail command and returns nonzero. Otherwise it reports that the service does not publish readiness and returns once spawned.
stop terminates an active run and its services. Use --service <name> (-s, matching restart) to stop only that service; other services keep running. Stopping an already finished service is a no-op. Stopping the last live service finishes the run. A stopped service in a still-active run can be started again with restart --service <name>. For how to choose a run or service, see devsess docs read selecting; for an orphaned group that needs --force, see devsess docs read troubleshooting.