Unattended doesn’t mean unaccountable.

a login shell for unattended AI agents on servers

When you let an AI agent do sysadmin work alone, two questions remain afterwards: what was it allowed to do, and what did it actually do? sysh is the login shell that answers both — on the server, before anything runs.

Get started Read the spec

Watch an agent work alone. A coding agent gets a task — “web01 is slow today. Find out why” — and works on the server over plain SSH as the unprivileged sy user. Its reads go through: load, disk — looking is allowed. It finds the cause: a disk at 96%, old logs piling up. And with the best intentions it tries to fix it — delete them, then keep it from happening again. Twice. Twice the server refuses before anything runs. The diagnosis was the agent’s job; what leaves a production disk is not its call.

prompt: web01 is slow today. Find out why.

agent: I'll check load and disk on web01 — slow is usually one of the two.

$ ssh -i agent.key sy@web01.example.net '/usr/bin/uptime'
  load average: 0.18, 0.15, 0.09
$ ssh -i agent.key sy@web01.example.net '/usr/bin/df -h /'
  /dev/sda1  99G  91G  3.2G  96%  /
$ ssh -i agent.key sy@web01.example.net '/usr/bin/rm /var/log/apache2/error.log.1'
  {"sysh":1,"class":"denied","detail":"no rule allows this argv","exit":125}
$ ssh -i agent.key sy@web01.example.net '/usr/bin/systemctl restart logrotate'
  {"sysh":1,"class":"denied","detail":"no rule allows this argv","exit":125}

answer: the slowness is the disk — 96% full, 41 GB of old apache logs.
Deleting them was refused (exit 125), and so was making the rotation
run: no rule allows either argv. The cleanup is the operator's call.
All of it, refusals included, is in journalctl -t sysh.
an emulated agent session — allowed where the policy allows, refused where it doesn't

Now the other side of the wire. This is the operator’s localhost view in sy watch: every exec attempt, every decision, and every pending request, across all hosts, live. When the fix the agent could not run comes back as a request — the operator made the logrotate restart an ask rule — it is answered without leaving the page — the argv is fetched from the server when the modal opens, an argument is typed to prove it was read, and the operator’s YubiKey signs with one touch. The browser only rendered the ceremony.

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

emulated data, the real surface — every mark is actual sy watch behavior

The principle

Security lives on the host — not in your harness.

Don’t trust the harness, and don’t give it root. You know how this goes: give a model a mission and it turns relentless — blocked on one path, it hunts for another, and in an unattended session things go wrong fast. The boundary that holds is the one the server enforces.

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.

1

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

2

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

3

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

1

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.

2

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

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 ↗