Usage

The whole lifecycle: the package does the host-local setup, the operator writes the policy and adds the agent key over plain SSH — and from then on anyone the policy allows, human or agent, works inside it.

STEP 1Install

One .deb from the releases page (Debian 12 / Ubuntu 22.04+). The package creates the sy user, installs the sshd drop-in, the tmpfiles.d entries and — if auditd is present — UID-scoped audit rules. No debconf, no daemon.

$ apt install ./sysh_0.6.0_amd64.deb
$ sysh doctor      # 0 failures, 0 warnings before you go further

STEP 2Write the policy

The policy is a root-owned TOML file at /etc/sysh/policy.toml. Rules match the literal argv — fixed absolute paths, anchored patterns, no shell semantics. Install it with the built-in linter:

$ cat > policy.toml <<'EOF'
mode = "enforcing"

[[rule]]
argv = ["/usr/bin/uptime"]

[[rule]]
argv = ["/bin/df", "-h"]

[[rule]]
argv = ["/usr/bin/systemctl", "status", "[a-z0-9@._\\-]+"]

# deny rules have prefix semantics and win over any allow
[[rule]]
argv = ["/usr/bin/"]
action = "deny"
EOF
$ sysh policy install policy.toml

The linter rejects over-broad patterns and known escape-hatch binaries — shells, interpreters, find, xargs, tar, git, ssh, docker… If it complains, the policy does not install: the failure direction is safe.

STEP 3Add the agent key

Generate a dedicated key for the agent and register it by fingerprint. The key's comment becomes its identity in every event:

$ ssh-keygen -t ed25519 -f agent.key -C sy/server.example
$ sysh auth add < agent.key.pub    # forced options: no PTY,
                                   # no forwarding, sysh as the shell
$ sysh auth add --ttl 7d < agent.key.pub   # or with an expiry the
                                   # gateway itself enforces

Keys are low-value by design: a stolen one reaches only the policy’s argv surface, journaled. An expired key is refused like any other deny; sysh auth rotate <key-id> swaps in a fresh key without a lockout window, and sysh doctor warns when one is about to lapse. No certificate authority — the TTL is a date in the root-owned keys.map, checked on the host before anything runs.

STEP 4Use it

From then on the agent — or you — connects as sy over plain SSH:

$ ssh -i agent.key sy@server '/usr/bin/uptime'
$ ssh -i agent.key sy@server '/bin/df -h'
$ ssh -i agent.key sy@server '/usr/bin/sudo -n id'
{"sysh":1,"class":"denied","detail":"denied by deny rule","exit":125}

Exit codes: 2 lockdown, 3 malformed input, 124 timeout, 125 denied or internal error, 30 approval required, 31 result unavailable. Each exec gets a systemd scope with resource caps; output above the cap trips and is recorded.

The channels are separated by design: the command’s stdout streams back untouched — parse it for data — and the JSON envelope above goes to stderr. There is no shell on the server, so a remote pipe is refused with the reason, and filtering belongs on your side of the wire:

$ ssh -i agent.key sy@server '/usr/bin/uptime | grep load'
{"class":"denied","detail":"no shell operators here: send one
command per exec (argv is split on whitespace, && ; | are literal
words)","exit":125}
$ ssh -i agent.key sy@server '/usr/bin/uptime' 2>/dev/null | grep load
load average: 0.18, 0.15, 0.09

STEP 5Root on request: approval rules

Between “never root” and “pre-authorized root” there is a middle: the agent can ask. A rule with approval = true grants nothing standing — each execution waits for a human:

[[rule]]
argv = ["/usr/bin/systemctl", "restart", "[a-z0-9@._\-]+"]
path  = "/usr/bin/systemctl"
privileged = true
approval = true       # root, but only per-exec, human-gated
timeout = 60

At runtime the agent's call exits 30 with a request id and executes nothing. You answer from any root SSH session:

$ ssh -t root@server 'sysh approvals'
req_9b3c1d5e7a42  age=3s  key=sy/server.example
  argv=["/usr/bin/systemctl","restart","mariadb"]
$ ssh -t root@server 'sysh approve req_9b3c1d5e7a42'
  execute as root? [yes/no] type argument 2 exactly as shown (mariadb):
executed: exit=0 in 213ms

The approver re-reads the argv on screen and types any pattern-chosen argument by hand; a mismatch aborts and the request stays pending. The agent then fetches the outcome read-only — sysh-result req_…, exit 31 while pending, expired, or never approved. The journal holds both halves: request events from the agent's side, approve events from root's (_UID=0). Requests expire after 10 minutes, results after an hour; there is nothing to revoke because nothing was ever granted.

Signed approvals bind approval power to registered approver keys — for headless or remote operation, and for FIDO2-grade assurance. Register your key once (an sk-* hardware key means no signature can exist without your physical touch):

root@server# sysh approver add ops-yubi
paste one public key line, then Ctrl-D
registered approver ops-yubi (sk-ssh-ed25519@openssh.com)

Then approve from anywhere, signing the exact request bytes with stock tooling:

$ ssh root@server 'sysh approve req_9b3c1d5e7a42 --show' > req.body
$ ssh-keygen -Y sign -f ~/.ssh/id_ed25519_sk -n sysh-approve req.body
$ cat req.body.sig | ssh root@server 'sysh approve req_9b3c1d5e7a42 --sig'
approved by ops-yubi (SHA256:…); executed: exit=0 in 198ms

The signature is verified in-process on the server, bound to the request’s exact bytes and the sysh-approve namespace; an unregistered key, a wrong file, a replayed signature — all refused, request stays pending. The typed-argument challenge of interactive approve still applies to pattern rules.

One command wraps the whole ceremony — sy approve, run by you in your terminal (never a tool the agent can call): it fetches the request bytes from the server over your root SSH channel, shows the server-recorded argv, and runs the sign+submit with your approver key (YubiKey PIN and touch happen inside):

op@laptop$ sy approve req_9b3c1d5e7a42
┌─ sysh approval request req_9b3c1d5e7a42 ──────────────
│  key: sy/server.example (claimed)  age: 8s
│  argv: /usr/sbin/reboot
└─ sign with your approver key to authorize exactly this ──
authorize exactly this? type yes to sign: yes
insert your YubiKey… (waiting up to 30s)
authenticator detected
signature ok: approver ops-yubi (…); executed: exit=0 in 30ms

The display comes from the server through your own channel — the agent cannot fake that screen, which is exactly why the approval gesture lives here and not in agent tool space.

But wait — why can’t the agent just run sy approve itself?

A fair first reaction, and the design’s load-bearing wall. The server never trusts anything on the laptop: it accepts only signatures from registered approver keys, verified root-side. So the question collapses to one thing — can any process produce that signature? Three walls stand between the agent and the pen:

  1. The hardware gesture. With an sk-* approver key on a FIDO2 token (YubiKey), every signature requires the token’s PIN and a physical touch, inside ssh-keygen. The key material never leaves the token — export is not a thing. An agent running wild on your laptop can invoke the whole ceremony a thousand times, drive synthetic TTYs, whatever: without a human finger on the token, no signature exists. The touch is the only input no process can synthesize.
  2. User separation (deployment requirement DR1). The agent harness runs as a dedicated OS user holding only agent keys — never your root SSH keys, never your ssh-agent, never ControlMaster. It cannot even launch the ceremony with your credentials: to it, your approver key and root channel are unreadable. (This is also why the root SSH channel — the real trust root on the laptop — must carry a gesture of its own: passphrase not auto-loaded, or ssh-add -c confirmation per use.)
  3. The honest edge, named. Same-user malware can still drive a ceremony and fake what you read (a phishing variant: screen says reload, bytes say reboot). The touch proves a human acted; it cannot prove what the human saw. That is why you type sy approve yourself in your own terminal, why the argv box comes from the server over your channel, why you re-type the pattern argument by hand, and why the root-side journal records what was actually signed — detection, always.

The hardware token is the workflow

Everything above assumes one small object in your USB port. The integration is deliberately boring — stock OpenSSH, no drivers, no proprietary daemon:

$ ssh-keygen -t ed25519-sk -f ~/.config/sy/keys/approver-sk -N ""
You will need to enter the token PIN, then touch the token…
Your identification has been saved in .approver-sk

What lives on disk is only a key handle — a reference to a key sealed inside the token’s secure element. Register it once, root-side, like any approver:

root@server# sysh approver add ops-yubi
paste one public key line, then Ctrl-D
registered approver ops-yubi (sk-ssh-ed25519@openssh.com)

From then on, the token participates exactly twice per approval: ssh-keygen asks the FIDO2 PIN (three bad tries lock the token’s sysh use until replug; eight wipe it — brute force is not on the menu), and the token blinks for a touch. No PIN prompt and no touch anywhere in the agent’s tree, ever — sy approve runs in your terminal, as you. Lose the token and the approver simply stops signing; remove it root-side and the ceremony reverts to interactive ssh -t from a root session.

STEP 6Batch work: agent scripts

One exec per command is fine for reading; real work comes in batches. sysh gives the agent progressively more shell — every step still argv-governed. This is the operator’s dial:

what the agent sendsshell featurespolicy checksjournal seesa refusal
direct exec ssh sy@host '/usr/bin/uptime' none — pure argv the argv: exact rules, denylist, approval pre/post pair per exec stderr line + exit 125
console same, line by line in a REPL none, plus cd state identical to direct exec identical, plus builtins identical
lines script #!/usr/bin/sysh + one command per line none — a batch of argvs every line, same pipeline pre/post per line stops the script at that line
traced script any bash/python script, pipes and all full interpreter every execve in the tree pre/post per exec, nested included -EPERM in-band; the script’s logic decides
root mode anything at all everything denylist only (your deny rules) top-level argvs as root — the tree inside is not visible only what you denied

Two policy fields pick the script flavor:

agent_scripts = "/var/lib/sysh/agent-scripts"
agent_scripts_mode = "lines"   # the default

In lines mode a script is data: first line #!/usr/bin/sysh, then one command per line — and every line is policy-checked and journaled exactly like a direct exec. No shell features inside; a refused line stops the script with the teaching detail on stderr. The agent uploads scripts through an operator-acknowledged rsync rule scoped to the directory — there is no other way in.

In traced mode the directory holds real scripts — any shebang the operator allows installed — and the argv policy extends into the process tree: a ptrace tracer intercepts every execve, checks it with the same rules, and a refusal fails the syscall (-EPERM) — the interpreter sees “Operation not permitted” and the script’s own logic decides whether to go on:

agent_scripts_mode = "traced"

# in a bash script: the pipe is bash's plumbing, but each side is a checked exec
/usr/bin/uptime | grep average
allow argv=["/usr/bin/uptime"]
deny  argv=["grep" "average"] — bash: /usr/bin/grep: Operation not permitted

Honest limits, stated in the lint and PROJECT.md §6.13: only execve is inspected (interpreter builtins are not argv-visible), it is argv enforcement — not sandboxing — and sudo touch /run/sysh/traced-off refuses every traced run instantly. amd64 hosts only.

Trade-offs, bottom to top: lines mode shows you everything the agent runs and offers it no shell at all; traced mode gives it a real interpreter — pipes, variables, control flow — while every program it invokes is still checked and journaled (interpreter builtins are not argv-visible; that is the OS layer’s bound, not the argv’s); root mode is the honest opt-out: total freedom, journal only, host disposable. Moving up the table, the agent gets more shell and you see less of how it works, never less of what it runs at the argv level — except root mode, where you see only the top.

For humans there is also a small interactive console: ssh sy@host with a TTY opens a banner, help, and cd navigation state — every line through the same checked, journaled pipeline.

STEP 7Root verbs: privileged rules

For work that needs root, the operator pre-authorizes exact argvs. Install generates a root-owned sudoers fragment limited to those argvs — nothing else:

[[rule]]
argv = ["/usr/bin/systemctl", "reload", "apache2"]
path  = "/usr/bin/systemctl"
privileged = true
ack  = true          # required: you said so, out loud
timeout = 60

At runtime the gateway wraps the exec in sudo -n --; events carry PRIV=true with the agent's argv, and sudo writes its own independent PAM journal line. The trade-off — no-new-privs must be dropped for the tree while such rules exist, and sudo's TIMEOUT= enforces the deadline — is documented in PROJECT.md §6.8.

Profiles: composing with OS permissions

Fine-grained shapes come from composing the argv policy with ordinary OS permissions, prepared in the attended phase. The worked example — an agent-maintained web server: read the Apache config tree and logs, write the enumerated config files, validate, reload — lives in examples/webserver/:

# OS side (operator, once): ACLs carry the log reads — no groups needed
setfacl -m u:sy:rX /var/log/apache2
setfacl -d -m u:sy:r /var/log/apache2      # survive logrotate

# policy side: the verbs (privileged rules are exact argv)
[[rule]]  argv = ["/usr/bin/tail", "-n", "[0-9]+", "/var/log/apache2/error.log"]
[[rule]]  argv = ["/usr/sbin/apache2ctl", "configtest"]   # privileged
[[rule]]  argv = ["/usr/bin/tee", "/etc/apache2/ports.conf"]  # privileged
[[rule]]  argv = ["/usr/bin/systemctl", "reload", "apache2"]  # privileged
[[rule]]  argv = ["/usr/bin/systemctl", "restart", "[a-z0-9@._\-]+"]  # approval-gated

The agent then maintains that server — config content on stdin through tee, validate, reload — and nothing else. A full restart drops live connections, so it goes through the approval channel: the agent can only request it, a human answers.

Root mode: total freedom, recording only

For a custom host you consider disposable, there is an explicit opt-out. Deny rules are the only rules; everything else runs as root through a wildcard sudoers grant the install writes:

version = 2
mode    = "root"
timeout = 300              # per-exec bound, seconds (required)

[[rule]]  argv = ["/usr/bin/rm"]     # prefix match: rm with any args
deny     = true

Every argv is still journaled, scoped, and time-bounded — but this is freedom with a record, not control. After the first root exec the agent can mint access the journal never sees: a new key, a changed shell, a parallel session. Install requires active auditd rules, allow rules are a lint error (they mean nothing here), and sysh doctor warns about root mode on every run. If you want rollback, snapshot the VM in your hypervisor first — outside sysh.

STEP 8Agent harnesses: sy mcp

The same package ships sy, the agent-side client. Point your MCP-capable harness (Pi, Claude Desktop, anything that speaks stdio MCP) at sy mcp and it gets three tools: sy_exec, sy_docs, sy_policy — nothing more. Hosts live in an operator-edited registry (~/.config/sy/hosts.toml), connections are plain SSH as the unprivileged sy user with strict known_hosts; the server-side policy is the only authority. When an exec needs root approval, the tool result carries the request id and tells the agent to stop — approval power never appears in tool space.

$ cat ~/.config/sy/hosts.toml
default = "web01"
[hosts.web01]
address = "web01.example.net"     # your host
key     = "~/.config/sy/keys/web01.ed25519"
$ ssh-keyscan web01.example.net >> ~/.config/sy/known_hosts  # all key types: servers may present ecdsa first
$ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | sy mcp

STEP 9Watching everything: sy watch

The journal that makes the record trustworthy makes it watchable. sy watch opens one read-only journalctl -t sysh -f follow per host in your registry — over the same root SSH channel sy approve uses — and renders a localhost web page: every exec attempt, every decision, every pending approval, across all hosts, live. No daemon and no listener on any managed host; the journal stays the only source of truth.

Beta — not yet battle-tested; the pending banner and the sy watch terminal remain the reliable channels. Click the bell in the header and the browser asks once: allow notifications? Answer yes and new approval requests pop as native alerts — argv, key, host — that stay on screen until answered, like a meeting invite. Clicking one focuses the page on the pending panel; the ceremony itself never leaves the server. (Notifications need localhost or HTTPS — sy watch is localhost by design.)

http://127.0.0.1:7321 loopback only · same-origin ceremonies
sy watch web01db01 ◐
search argv, key, host… allowdeny requestapproval
timehostkeyargvdecisionexit

A pending request is one click from answered, two ways. Approve here runs the whole ceremony in the page: when the modal opens, the server fetches the argv and the exact request bytes fresh (over the same root SSH channel it uses to follow journals), shows them, and asks you to type the last argument — proof you read what you are approving. Only then does it run ssh-keygen and your token touch happens, exactly as in the terminal: the argv shown is the argv signed, and the browser is only the renderer, the way a terminal emulator is. Run in terminal opens a terminal with sy approve already running instead. The surface is loopback-only (non-loopback refused, Host header validated so a visited page cannot DNS-rebind in) and same-origin-only for ceremonies (Sec-Fetch-Site + JSON, so visited pages cannot drive one); there is no exec path anywhere. If the typed argument feels like too much ceremony, sy watch --no-challenge makes the touch the only confirmation — a real trade-off (the forced reading of the argv is the anti-phishing layer), so the default keeps the typing. For pipes and grep there is a terminal-native sibling:

$ sy watch
sy watch: 2 host(s), journal history 1h
sy watch: open http://127.0.0.1:7321
$ sy tail web01 --since 30m
21:26:03 web01 sy/web01.example.net allow /usr/bin/uptime (exit 0, 58ms)
21:26:03 web01 sy/web01.example.net deny  /usr/bin/rm /etc/passwd
21:26:15 web01 sy/web01.example.net request [root] /usr/bin/id

Reading the record

$ journalctl -t sysh --since today    # every exec attempt, both phases
$ ausearch -k sysh_exec               # kernel-side: files touched, network
$ sysh doctor                         # drift and tripwire check
$ sysh lockdown                       # panic button: drop the key, exit 2

Going deeper