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:
- The hardware gesture. With an
sk-*approver key on a FIDO2 token (YubiKey), every signature requires the token’s PIN and a physical touch, insidessh-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. - 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, neverControlMaster. 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, orssh-add -cconfirmation per use.) - 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 approveyourself 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 sends | shell features | policy checks | journal sees | a 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.)
| time | host | key | argv | decision | exit |
|---|
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
- README — the full feature walk-through and honest limits. read it ↗
- PROJECT.md — the specification: threat model, §6 gateway, §6.8 privileged execution, two security-review rounds with dispositions. read it ↗
- examples/ — three worked policies, validated on real hosts: diagnostic (read-only agent — read-only-ness by omission), operational (diagnose freely, act only through the approval channel), and the webserver maintenance profile with its OS-side setup. browse them ↗