Sentinel help & setup guide

Sentinel orchestrates agents; Muzzle and Leash are the guardrails. Each run executes as a dedicated host user (the leashed account) with its file/network/command access enforced by Leash, and its model I/O inspected by Muzzle. You operate Sentinel from a CLI — most often the interactive chat shell.

• Requires Muzzle and Leash on the same host (the installer verifies/installs both).
• Linux only. No public download yet — built from source.
• Run agents as the leashed user: `sudo -u <user> sentinel chat`.

Run the installer from the v1 directory on a root-capable Linux host. It verifies (and can install) Muzzle + Leash, lays down /opt/sentinel/v1, a default config, the CLI, and a systemd unit. Then `sentinel init` registers the agent's user with Leash, creates its state, a default `main` agent, a workspace, and seeds the bundled skills.

sudo bash install.sh
sudo systemctl daemon-reload
# register user 'fido' with Leash, check Muzzle, seed ~fido/.sentinel + a main agent
sudo sentinel init --leash fido --muzzle

• Install tree: /opt/sentinel/v1 · Config: /etc/sentinel/sentinel.yaml · CLI: /usr/local/bin/sentinel.
• Per-user state: ~<user>/.sentinel/{agents,skills,memory,runs,workflows} · workspace: ~<user>/workspace.
• Reinstalling preserves an existing config (defaults go to <config>.example).

`sentinel chat` opens a colorized REPL — the fastest way to drive an agent. Run it AS the leashed user so tools execute under that account and write to its workspace. It streams live progress, asks for approvals inline (y/N), keeps ↑/↓ history, and pops completion menus for `/` commands, `@` specialists, and `$` skills.

sudo -u fido sentinel chat
# inside the shell:
/agents                 # list the roster
/use writer             # switch the active agent
/model gpt-oss:20b      # pick a model (menu of config + upstream models)
@researcher summarize the latest notes   # send a task to a specialist
$                       # browse + attach skills
/status   /memory   /workflows   /quit

• A flagged action prompts `⚠ approve …? [y/N]` right in the flow.
• Bare filenames (e.g. notes.txt) land in the user's workspace.

Agents are saved profiles — a soul (persona), a bound model, skills, and tools. A main agent can delegate to a specialist or spawn a temporary one. Manage them with the `agent` subcommands and run one directly with `run --agent`.

echo 'You write files precisely.' > /tmp/writer.txt
sudo -u fido sentinel agent create writer --model gpt-oss:20b \
  --description 'writes files' --soul-file /tmp/writer.txt --tool write_file
sudo -u fido sentinel agent add-skill writer file-discipline
sudo -u fido sentinel agent list
sudo -u fido sentinel run --agent writer "Create report.txt with the notes."

A workflow is a named multi-step pipeline. Each step runs an agent on a task; outputs thread into later steps via `{{input}}`, `{{<step>.output}}`, and `{{previous}}`. Run it from the CLI, the chat (`/workflow run`), or let an agent call the `run_workflow` tool.

sudo -u fido sentinel workflow create brief \
  --description 'research then write' \
  --step 'researcher::List key facts about {{input}}.' \
  --step 'writer::Write brief.txt with exactly: {{researcher.output}}'
sudo -u fido sentinel workflow run brief --input 'local LLM runtimes'

Sentinel is driven by /etc/sentinel/sentinel.yaml — the leashed user, the Muzzle endpoint, configured models, the per-tool approval policy, the default agent, and the temporary-subagent disposition.

leashed_user: fido
muzzle_endpoint: "http://127.0.0.1:11434"
models:
  - { name: local,   provider: ollama, model: "llama3.2:latest" }
  - { name: gpt-oss, provider: ollama, model: "gpt-oss:20b" }
default_agent: main
subagent_disposition: discard   # discard | save | ask
tools:                          # per-tool policy: auto | needs_approval | deny
  read_file: auto
  write_file: needs_approval
  run_command: needs_approval
  delegate: needs_approval
  run_workflow: needs_approval

• An agent's model can be a config name (e.g. `local`) or any raw id the Muzzle upstream has.
• `needs_approval` tools pause for a yes/no; `auto` runs; `deny` is refused. Unknown tools fail closed (need approval).

Beyond `chat`, the CLI runs and inspects work headlessly. Headless runs use the async approval queue; the chat approves inline.

sudo -u fido sentinel run "Summarize today's notes."
sudo sentinel runs                 # list runs
sudo sentinel approvals            # pending approvals
sudo sentinel approve <id>         # approve + resume a run
sudo sentinel status               # config + Muzzle/Leash health + model checks
sudo sentinel logs --follow        # tail the event log

The uninstaller removes the install tree, config, unit, and CLI wrapper (leaving the host user).

sudo bash uninstall.sh