Sshboard

sshboard

*English ／ 日本語*

Your AI agent and you, looking at the same server, on the same screen, over one SSH connection.

You keep your own SFTP client and your own terminal. The agent works beside you — inside a fence you drew — and every single thing it does scrolls past in your window while it happens.

⚠️ This is alpha. It is in use on production servers (investigating a failed

certificate renewal, restarting pm2, and so on). Installers are published for Windows

(x64 / ARM64) and macOS.

Passing tests does not mean it works as a tool — we shipped a build whose terminal

displayed *not one byte* for three days (Issue #10).

[⬇ Download](https://github.com/meta-taro/sshboard/releases/latest) · Direction · Every decision, with its reasoning

---

When you would reach for this

"Renew the certificates on three hosts, today"

You have a terminal open per host and you are copying the same command into each, watching for the one that fails. sshboard opens one console per connection — or two on the same host, side by side — and the agent can read *all* of them while you work. Not "the agent runs it for you": the agent watches what you are doing and tells you which pane went wrong.

"Mail stopped arriving and I don't know where to look"

You ask the agent. It reads /etc/postfix/main.cf, checks the service, tails the log — over the same SSH session you are already on, and you see each step as it happens. It cannot run an arbitrary command to do it: there is no `run_command(cmd)` tool.

[Human] $ cd /var/www

[AI] $ df -h Filesystem Size Used Avail Use% Mounted on /dev/vda1 50G 38G 10G 80% / [AI] read /etc/postfix/main.cf (4.1 KB)

"I want help, but not an agent loose on my server"

The agent may write only inside directories you listed, one connection at a time. The list starts empty, so it cannot write a single byte until you say where. Delete, rename, move, chmod, restart, package installs, sudo — none of them exist for the agent. You are not restricted anywhere.

---

Try it in five minutes

Install the app, then point your agent at it. There is nothing else to run — the MCP server lives inside the app.

# 1. a throwaway SSH server on your own machine (needs Docker)

sh tools/test-server/up.sh ssh-add tools/test-server/.key

2. the app

pnpm install pnpm --filter desktop tauri dev

Register 127.0.0.1:2222, user probe, connect, then press Copy the MCP command in the window's title bar and paste it into your agent:

claude mcp add --scope user --transport http sshboard http://127.0.0.1:22022/mcp \

--header "Authorization: Bearer "

Prebuilt installers are on the releases page (Windows x64 / ARM64, macOS Apple Silicon). They are not code-signed, so SmartScreen and Gatekeeper will both stop you the first time.

---

What you see while the agent works

Every operation, yours and the agent's, lands in one band. You do not have to ask what it did.

![The activity band: one line per operation, with [AI] marking the agent's](site/shots/en/band.png)

When something fails, the same log the agent reads over MCP is on your screen — which stage it reached, why it stopped, and what to do next. It carries no hostnames, no usernames and no secrets.

Why this exists

There are services still running on ordinary shared hosting and VPSes. Maintain one of those *with* an AI agent and this happens every single time:

you : I want to fix this service's config

AI : I can't see the server, so please tell me its state you : (open a terminal, look, paste) AI : now show me that config file too you : (open SFTP, download, paste)

This tool exists to delete that round trip. The agent does not need to *operate* your server. Letting it see is enough.

How you actually use it

This is not a tool you drive by clicking buttons. You talk to an AI agent in your terminal, and the agent calls sshboard's built-in MCP server.

you → the AI agent in your terminal: "mail isn't arriving. look into it"

│ │ MCP (inside the app — no extra process) ▼ sshboard ── one SSH ──▶ server │ (sftp / exec) ▼ an [AI] line scrolls past in sshboard's window ── you are just watching. what it read and what it typed is visible as it happens

[Human] $ cd /var/www [AI] $ df -h Filesystem Size Used Avail Use% Mounted on /dev/vda1 50G 38G 10G 80% / [AI] read /etc/postfix/main.cf (4.1 KB)

You are not restricted. The two-pane file browser and the terminal tab work like any other SFTP client and terminal. Only the agent's side is fenced.

What the agent may call (Phase 1 — reading)

list_connections / list_directory / stat / read_file / search / download / disk_usage / process_list / service_status / runtime_versions / read_log / network_listen / run_readonly (allowlist) / list_checks / run_check / propose_check (health checks)

There is no `run_command(cmd)`. One such tool does everything, and once you have it the only thing standing between an agent and a destructive command is a promise not to use it. A promise is a runbook, not a gate.

With run_readonly the agent may pass only an id that a person wrote into `readonly.toml`. There is no argument slot. The list ships empty — until you write it, nothing runs at all. Refusals show up in the window's activity band and are recorded in readonly-refused.log. Adding entries is a person's job.

The one success criterion

The agent stops saying "please tell me the state of the server."

Not downloads, not stars. Whether the round trip disappeared during real maintenance.

It will not modernise your setup

• This is not a tool for migrating your server somewhere else
• Working with the setup you already have is the point
• These services will still be here in ten years. Nothing exists today that brings AI development to them

Shape

   ┌──────────┬──────────┐        ┌──────────┐

│ files │ terminal │ │ MCP │ │ two-pane │ tab │ │ │ └────┬─────┴────┬─────┘ └────┬─────┘ └──────────┴───────┬───────────┘ ▼ ┌────────────────────────┐ │ Operation Engine │ ← exactly one implementation lives here └───────────┬────────────┘ ▼ one SSH connection (sftp / exec)

We do not keep two SFTP implementations, and we never open an SSH session you cannot see. Being invisible is the single biggest danger here.

Whoever touched what flows into the same band. Different surfaces, one record.

[Human] $ cd /var/www

[AI] $ df -h Filesystem Size Used Avail Use% Mounted on /dev/vda1 50G 38G 10G 80% / [AI] read /etc/postfix/main.cf (4.1 KB)

Phase 1 is read-only

No writes at all. Every intended use — incident triage, mail-config investigation, writing up a proposal — is reading. That makes the risk close to zero, which means you can point it at a live production server on day one.

There is no run_command(cmd)

Put one arbitrary-command tool in place and it can do everything. That is exactly why it does not exist.

• Hand it over and the only remaining defence against a destructive command is a promise
• A promise is a runbook, not a gate
• With an allowlist, dangerous commands are not expressible

What readonly.toml looks like (a person writes it)

version = 1

[[command]] id = "uptime" # the only value the agent may pass run = "uptime" # what actually runs. exactly what a person wrote description = "how long it has been up"

The product ships with zero entries. Nobody has the list of what real maintenance needs, and filling it in by guesswork gets it wrong. Refused calls pile up in readonly-refused.log — read that, and add only what was genuinely needed.

What this cannot verify: whether the run you wrote is truly read-only. The product cannot know. No machine can tell uptime from rm -rf / by inspection. What this prevents is exactly one thing: the agent composing a command string.

The human side (the GUI) is not restricted. Use it as an ordinary SFTP client and terminal. Only the agent's side is fenced.

Health checks (checks.toml)

Group the things you look at in the same order every time — disk, memory, a service, a listening port — into one check. Write it once; a person runs it from the menu (Checks → Run) and an agent runs the same check with run_check.

• A step only names an id from `readonly.toml`. There is no field for a command line
• Criteria come in fixed shapes only: text present (contains) / absent (absent), a number below / above a limit
• Each step comes back good, bad or unknown. Something that could not be measured is never counted as good
• The run does not stop at the first bad step, and the previous value sits beside the new one (until the app quits)
• Every step shows on the band before it runs. Checks the agent runs appear in the Checks dialog too
• The list ships empty. A person writes it; the agent cannot
• The agent can propose a check with propose_check. Every step and criterion appears on screen, and only the person can save it (saving runs nothing)

A template lives in docs/checks.example.toml.

State-changing operations (operations.toml)

The list ships empty. Until you write this file, the agent can run nothing.

This is a separate file from the read allowlist (readonly.toml), so that write operations never live in a file called readonly. Telling them apart by name is the point. Put it next to connections.toml.

version = 1

[[operation]] id = "restart-httpd" run = "sudo systemctl restart httpd" description = "restart Apache" max_per_hour = 3

Gates it passes through before running

1. It is in the list a person wrote. Unknown ids are refused, and the refusal is recorded
2. It is under the hourly ceiling
3. A person approves it on screen. The agent's first call is always refused, and the window shows what would actually run
4. An approval is spent once. One approval, one run
5. An approval expires after five minutes. People press allow and the agent never calls back (the conversation moves on). We do not leave approvals lying around — with become = "ask", the password is dropped here too

A person at the screen does not pass 3–5. They are looking at it. The one exception is the `become = "ask"` password — that is not approval, it is a credential, and the product cannot invent it.

Refused even if you write it down

No setting enables these. They are rejected even when present in operations.toml.

• The cage itself — sudoers / visudo / authorized_keys
• Keys — .ssh / `id_rs