The model
Three ways to let an agent work
Same host, same login, same record. The only variable is how much you trust the work — and every command lives in exactly one of these.
It can look, not touch
Reads, checks, diagnostics — granted one by one and exactly. The agent can answer “what’s wrong with web01?” all day. It cannot change anything, and it never gets root.
start here — triage, health checks, reading logs
It can ask
When something needs root, the agent doesn’t have it: the
request waits. You see the exact command and answer it — one click
in sy watch, signed with a touch on your hardware
token. Nothing runs before you answer — and a no costs
nothing.
add it when it earns trust — the restart only a human should order
It can act — on what you wrote down
The routine you’d automate anyway: the enumerated write, the validation, the reload. Root included — but only the exact actions you listed, checked when you wrote them, recorded twice.
graduate the boring loop — nobody should babysit it
Start at 1. When its requests get repetitive enough to trust, add 2. Move what’s truly boring into 3. All three run side by side — and every attempt, in any of them, lands in the same journal.
The operator’s console
The approval ceremony, in your browser
A pending request used to mean a terminal. Now it is one click: approve here runs the whole ceremony in the page — with the same guarantees the terminal gives, because the rules never lived in the terminal. They live on the server.
the argv shown is the argv signed
When the modal opens, the server fetches the pending request and the exact bytes to sign — fresh, over the same root SSH channel it uses to follow journals. The process that shows you the command is the process that signs it; the browser is only the renderer, the way a terminal emulator is.
a typed argument, then the touch
The modal asks you to type the last argument of the argv —
proof you read what you are approving; a wrong typing burns the
ceremony and starting over means reading it again. Then your
YubiKey signs inside ssh-keygen, touch and all: key
material never leaves the token. (--no-challenge
drops the typing for touch-only confirmation — the default keeps
it.)
same-origin, loopback, journal-true
Ceremonies refuse anything that is not this page:
Sec-Fetch-Site and JSON content type keep visited
websites out, the server binds to 127.0.0.1 only,
and no daemon or listener exists on any managed host. What was
actually signed lands in the journal — kernel-attested, like
everything else.
How it works
The login shell is the control point
The agent logs in over plain SSH as an unprivileged system user whose login shell does four things — on the server, before any command runs. Control lives there: not in the agent's harness, not in prompt instructions, not in a management plane. The agent cannot talk its way past a shell.
Records everything
Every command attempt — allowed or denied — with the full argv, the invoking key, and the outcome, to journald and (opt-in) auditd. The agent cannot forge or erase the record.
Delimits what runs
A root-owned policy of exact commands: literal argv matching, no
shell semantics, anchored patterns only, a mandatory linter that
rejects escape hatches — shells, find, xargs,
git, docker…
Refuses to elevate
Every process runs under no_new_privs: setuid and sudo
are kernel-disabled for the whole agent tree. Root work happens only
through operator-written privileged rules: pre-authorized
exact-argv grants, or a per-exec approval a human answers by hand.
One exception, named: mode = "root" — total
freedom on a disposable host, journal intact, control gone.
Expires its own keys
Agent keys are low-value by design: a stolen one reaches only the policy’s argv surface, journaled. Give one a TTL and the shell itself refuses it when it lapses — an expired key is denied like any other argv — and revocation is one root-owned command. No certificate authority, nothing extra to run or protect.
The workflow
Two phases: attended setup, unattended operation
Attended preparation
A human with root SSH — often working with a code agent at
their side — prepares the host: install the package, write the policy,
create the file-access shape it assumes (groups, ACLs, ownership),
deploy the agent key, run sysh doctor until it is clean.
The agent here is an assistant, not autonomous: supervised, interactive, reversible.
Unattended operation
The agent connects as sy over plain SSH and works alone
inside the bounds the operator set: the exact-argv policy, the OS-level
permissions beneath it, no-new-privs, per-exec scopes and resource
caps, full journald/auditd recording.
No human watches each command. The journal is the watch.
Honest limits
What sysh is not
These bounds are not infallible, and do not need to be. An allowed argv
is still a real program with real behavior — tee writes
whatever the agent pipes into the file it was granted. What you get is
bounded, recorded, root-free-by-default agent access —
defensible, where the alternatives are “give it a root shell” or “no
agent at all”. The full threat model is written out in
PROJECT.md.
Not a sandbox
The agent operates the real host, as a real unprivileged user. If you need isolation, run sysh inside whatever isolation you already have.
Not root-without-approval
Root work goes through sudo — but only via exact-argv sudoers grants your own policy install generates; the agent invoking sudo itself is denied. Unless you say so out loud: root mode grants every allowed argv as root. That is freedom with a journal, not control — after the first exec the agent can mint access the journal never sees. Disposable host, no snapshot integration.
Not monitoring
It audits its own channel into kernel-attested sinks. Shipping and correlating events is your existing stack's job — rsyslog, Wazuh, journal forwarding.
Not a harness
Works with any client that speaks SSH and passes an argv — scripts, CLI copilots, MCP bridges, humans. Your own SSH stays untouched.
Under the hood
It fits your stack
- One static Go binary — one .deb, no daemon, no management plane, no orchestrator; everything host-local.
- argv is the unit of trust — printable-ASCII split, exact-length matching, deny rules with prefix semantics; per-exec systemd scopes with resource caps and output limits.
- Fine-grained profiles by composition — the argv policy plus ordinary OS permissions (groups, ACLs, ownership) shapes access like “read the web server's logs and config, write the enumerated files, validate and reload”.
- Agent scripts, line or traced — batch work as
one-command-per-line scripts, or real interpreters (any shebang)
under a ptrace tracer that checks every
execvein the tree: the same argv policy, extended into the process tree. - Debian / Ubuntu today; it needs nothing beyond what a stock server already runs — journald and auditd are already there.
Go deeper
Get involved with sysh
Specification
Threat model, gateway internals, privileged execution, two external security-review rounds with dispositions.
read project.md ↗Examples
Three worked policies with READMEs: a read-only diagnostician, an operational agent that acts only through approvals, and the agent-maintained web server — each validated on a real host.
browse examples ↗Source & releases
GPLv3-licensed Go, one binary, buildable anywhere. Release .deb attached to every tag.
github.com/xezpeleta/sysh ↗