# Solo Run Processes

> Operate Solo-managed commands and terminals through start, stop, restart, rename, spawn, input, bulk actions, trust gates, auto-start, crash restart, and file-watch restart. Use when launching a dev stack, controlling project commands, renaming a process, opening terminals, sending input, or configuring restart behavior. Do not use for read-only status and readiness, project or solo.yml setup, or failure diagnosis.

- Skill: `kalepail/solo-run-processes` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add kalepail/solo-run-processes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kalepail/solo-run-processes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kalepail (https://skillmd.com/u/kalepail)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kalepail/solo-run-processes

---


# Run Solo Processes

Control existing process entries with smallest lifecycle action that achieves requested state.

## Workflow

1. Establish identity and scope.
   - Call `whoami` first when running inside Solo-managed agent.
   - Otherwise call `list_projects`, then `select_project` when multiple projects exist.
   - Use Solo process IDs from Solo tools only; never substitute OS PIDs or another orchestrator’s IDs.
2. Inspect before mutating.
   - Call `list_processes` or `get_project_status`.
   - Call `get_process_status` for target.
   - Confirm process kind, state, trust, and whether user requested one process or command batch.
3. Confirm authority and ownership.
   - Control only current process and Solo descendants this process spawned.
   - Record every returned child process ID at spawn time; do not reconstruct ownership from later process lists.
   - Require explicit user/runbook authority for parent, sibling, unrelated, YAML-backed shared process, or another agent's descendants.
   - Never infer ownership from idle, stopped, failed, completed, or handed-off state.
4. Respect trust.
   - Start/restart only trusted command processes.
   - If command is untrusted, report blocker and direct user to Solo UI review.
   - Never weaken or bypass trust to complete lifecycle request.
5. Choose exact action.
   - Call `start_process` for stopped stored entry.
   - Call `stop_process` for running entry.
   - Call `restart_process` when latest saved configuration must relaunch.
   - Use `start_all_commands`, `stop_all_commands`, or `restart_all_commands` only for explicit project-wide command request.
   - Call `spawn_process` only to create new terminal or agent; do not use spawn to duplicate configured command.
   - Record returned child ID immediately with purpose and owner.
6. Interact only when requested and authorized.
   - Call `send_input` for terminal text or control bytes.
   - Use `submit=false` to type without Enter.
   - Use bytes `3`, `4`, or `27` for Ctrl+C, Ctrl+D, or Escape.
7. Verify result.
   - Poll `get_process_status`; do not infer success from request acceptance.
   - Read short rendered output tail when startup confirmation matters.
   - Use port-readiness tools only when user needs service ready, not merely process running.
8. Report target, authority basis, action, final state, recorded child IDs, and skipped/failed entries.

## Runtime policy

- Treat `auto_start` as eligibility, not immediate launch. Project Auto Start, command flag, trust, and limits all gate startup.
- Use crash `auto_restart` only for commands expected to remain alive. Expect pause after 10 restarts in 60 seconds.
- Use `restart_when_changed` only when native watcher is insufficient. Keep globs narrow and project-root-relative.
- Keep crash restart and file-watch restart conceptually separate.
- Restart after shell environment or saved command configuration changes; existing child environment never updates in place.

## Safety

- Stop only requested scope. Project-wide actions affect commands, not terminals or agents.
- Use `close_process` only to remove terminal or agent. Use stop/restart for commands.
- Pass `confirm_self_close=true` only when user explicitly asks current process to close itself.
- Apply same ownership gate to stop, restart, close, rename, input, output clearing, UI selection, and timer delivery.
- Do not delete project or process definition when stop is enough.
- Do not clear output during lifecycle work; retained failure output supports diagnosis.
- Reuse existing dev process instead of starting duplicate service.
- Leave Git, publishing, deployment, and integration to root/operator.

## Boundary

- Hand initial repository/YAML architecture to project setup workflow.
- Hand agent setup, health, launch, resume, summaries, prompting, and cleanup to single-agent lifecycle workflow.
- Hand read-only URL, port, resource, and output inspection to service observation workflow.
- Hand repeated failure, environment mismatch, or unexplained state to troubleshooting workflow.

## Reference

Read [process lifecycle reference](references/process-lifecycle.md) before bulk actions, trust-sensitive starts, auto-restart/file-watch configuration, spawning, closing, or raw input.