dsh-service-control

Wings for the dsh command: manage the service's systemd lifecycle, persisted config and runtime diagnostics through dsh --profile ctl. No separate CLI (the legacy dshctl is gone).

Mechanism

The dsh launcher parses only its own flags (--profile/--patch/--dump-config) and hands everything after them to the booted app tree verbatim. This plugin takes over those inner arguments (via @deepseek-ai/dsh-cmdline) inside a dedicated lightweight ctl profile (dsh-base + plugin, no webserver/agent), executes the command and requests process exit. Each invocation boots a lightweight profile (~0.2-0.5s).

Install

# create the ctl profile and install (ctl is the conventional control-plane name)
dsh plugin --profile ctl add dsh-service-control

# local development install
dsh plugin --profile ctl add "file:/path/to/agents-plugins/dsh-service-control"

Do not install this plugin into the web profile — its command tree conflicts with the web app's own argument parsing. It only works in a webserver-less profile like ctl.

Commands

dsh --profile ctl <namespace> <subcommand> [args]

URL & launch token: since dsh 0.1.2 the web surface mints a random launch token per process start and the bare http://127.0.0.1:<port> returns 401. The url reported by start/restart/status and the address start opens carry the current launch token (read back from the log); health probes (probe/watchdog) treat 401/404 as “process alive” (HTTP layer reachable) and only count connection failure/timeout as unhealthy.

systemd lifecycle layering:

install        = managed: write units + register → crash self-heal / watchdog active, 【no autostart】
reinstall      = append env vars: keeps the whole unit file, only inserts/updates the --env keys
enable         = managed + boot autostart (auto-installs when units are missing)
disable        = stop watchdog + disable autostart (unit files kept, management stays)
uninstall/remove = revoke management: remove unit files

--env environment variables (install / reinstall, repeatable):

# explicit value
dsh --profile ctl systemd install --env OPENROUTER_API_KEY=sk-xxxxx567
# implicit: take the value from the current shell env (unset or empty → install fails)
dsh --profile ctl systemd install --env OPENROUTER_API_KEY
# multiple variables
dsh --profile ctl systemd install --env A=1 --env B=2
# append to an installed unit (keeps manual edits; keys already present are skipped with a notice)
dsh --profile ctl systemd reinstall --env OPENROUTER_API_KEY=sk-xxxxx567

Variables are written as Environment="KEY=value" into the [Service] section of the main unit ($ is kept verbatim; %, quotes and backslashes are escaped per systemd syntax). Note: environment variables of a unit are visible to same-user D-Bus clients, so they are not suitable for highly sensitive secrets; the implicit --env KEY form keeps the value out of shell history and the process command line. reinstall only runs daemon-reload and does not restart — new variables take effect on the next dsh --profile ctl systemd restart.

Note: plugin is a parser-level alias of self (the original design name; supported by the commander tree and unit tests). However, the dsh launcher has a built-in plugin subcommand (forwarding to pnpm) that intercepts any call whose first positional argument is plugin (neither --profile=ctl plugin nor the -- separator can bypass it), so use self in your shell.

self update semantics (by install source):

--check only preflights (reports install source and local/remote diff) without updating; since every dsh invocation is a fresh process, the update takes effect on the next call.

Target profile

ctl is the control plane; the managed service profile defaults to web. Override it in the ctl profile's cordis.patch.yml:

- id: dsh-service-control
  config:
    profile: tui

Completions (placed into each shell's default load dirs — no rc edits)

dsh --profile ctl completions --install          # install all three shells
dsh --profile ctl completions --install bash     # install bash only
dsh --profile ctl completions bash               # print the script only (no install)
dsh --profile ctl completions --write-state      # cache to $DSH_HOME/completions (optional)

--install places the generated scripts into each shell's default auto-load directory and never edits the user's .zshrc / .bashrc / fish config:

The scripts complete the dsh command itself (--profile ctl + the full command tree) plus each subcommand's options: self update --check, -f/--follow for svc logs / systemd journal, and --shell <bash|zsh|fish> / --write-state / --install for completions. Both --profile ctl and the --profile=ctl equals form are recognized; --shell values work in space and equals forms.

Config keys (config set whitelist)

Platform & dependencies

• Linux primary: bash, systemctl (optional — autostart commands error without it), pgrep/pkill, ss or lsof, curl.
• macOS partially supported (ss→lsof, probe latency falls back to node, browser falls back to open); systemd commands unavailable.
• Windows requires WSL.
• Dependencies: @deepseek-ai/dsh-cmdline, commander, @deepseek-ai/schemastery (Node ≥ 18).

Testing

npm test        # unit: command-tree parsing (aliases/flags/exit), completion generation,
                # control.sh systemd layering (install/enable/disable/uninstall), plugin shape
npm run smoke   # smoke: isolated profile install → composed-config assert → cmdline self info / systemd status

Uninstall

dsh plugin --profile ctl remove dsh-service-control   # remove the plugin itself
rm -rf ~/.dsh/profiles/ctl                            # (optional) drop the control profile
dsh --profile ctl systemd uninstall                   # (optional) revoke systemd management first