- 1 The runbook is in Confluence; the work is in SSH. Nobody updates Confluence at 2am. By 9am the fix is in a Slack thread and the doc is still wrong.
- 2 The commands in the doc don't match what actually fixed it last time. The flag changed in v15. The systemd unit renamed. The doc reflects a system that hasn't existed for eighteen months.
- 3 Search is bad enough that the on-call rebuilds the runbook from scratch every incident. Wiki search returns 40 hits, half of them archived, none of them the one you need. You start over.
- 4 The senior engineer's "I know this one" never makes it into a doc. The fix lives in one person's head. They leave, and the institutional memory walks out with them.
For SREs, devops, and on-call
Runbooks that live next to
Runbooks that live next to
the systems they describe.
Markdown runbooks in the same Space as the SSH connections, HTTP requests, and DB queries they reference. Magellan drafts them from real session output. Every edit lands in audit.
Download free for macOS, Windows, Linux
Free forever · No credit card · Versioned docs on Team+
ShellYard · Production Space
Runbook · failover.md
ssh · pg-replica-02
psql · pg-primary
failover.md v7 · saved 2m ago
# Postgres replication failover
## Symptoms
- Replica lag > 30s
- pg_stat_replication shows no rows
- App writes succeed; reads stale
## Verify
```bash
psql -h pg-primary -c \
'SELECT * FROM pg_stat_replication'
```
## Restart standby
```bash
sudo systemctl restart \
postgresql@15-main
```
## Confirm catch-up
Wait for pg_last_wal_replay_lsn()
to match the primary.… ssh pg-replica-02 ● connected
postgres@pg-replica-02:~$ psql -h pg-primary -c \
'SELECT pid, client_addr, state,
sync_state, replay_lag
FROM pg_stat_replication;'
pid | client_addr | state | …
------+--------------+--------+-----
(0 rows)
postgres@pg-replica-02:~$ sudo systemctl \
restart postgresql@15-main
● postgresql@15-main.service - PostgreSQL
Active: active (running) since…
postgres@pg-replica-02:~$ psql -c \
"SELECT pg_last_wal_replay_lsn();"
pg_last_wal_replay_lsn
------------------------
3F/9A1E22B0
(1 row) 3 lines selected in terminal
Save selection → Runbook in Production Space
Why your runbooks rot
Documentation that lives away from the work goes stale on contact.
The new motion
Write the runbook IN the incident, not after it.
- 1 Open the connection. Run the commands. The output stays in the terminal pane next to your editor — no scrollback grep, no "what did I run again" five minutes later.
- 2 Select the relevant output. Click "Save as runbook" or "Draft with Magellan". The terminal selection becomes a markdown code fence. Magellan adds the surrounding prose if you ask it to.
- 3 Markdown editor pre-fills with what you actually did. Edit. Add the symptoms section. Save to the Space. Tiptap WYSIWYG view toggles to source — never lose formatting.
- 4 Next on-call finds it next to the connection it was diagnosed through. Open the Postgres connection in the Production Space — the runbook is one tab over. Version history shows what changed and who changed it.
What ships
A real markdown editor. Wired to the work.
Markdown editor that knows what a runbook looks like.
Headings, code fences with syntax highlighting, callouts, tables, images. Tiptap WYSIWYG round-trips to source — toggle between rich edit and raw markdown without losing formatting.
Magellan drafts FROM the session.
Ship terminal output, an HTTP response, a DB query, or a config diff to the AI; ask for a runbook draft. BYO Anthropic / OpenAI / Gemini / Ollama key. Prompts go direct to the provider, never through us.
Version history with side-by-side diff.
Every save is a version. 90-day retention on Team, unlimited on Enterprise (subject to per-Space byte cap). Side-by-side diff viewer shows what changed between v6 and v7.
Per-Space audit on every doc edit.
Actor, timestamp, target, action — logged on every save, every share-link mint, every revoke. CSV export at Team+ for client-facing reports or compliance reviews.
How it differs
ShellYard vs. the wiki you have today.
| ShellYard | Confluence | Notion | Markdown in Git | |
|---|---|---|---|---|
| Docs scoped to the systems they describe | Same Space as the SSH/DB/HTTP connection | Separate browser tab | Separate browser tab | Separate repo / editor |
| Version retention | 90d (Team) / unlimited (Ent) | Tier-dependent | Page history (plan-dependent) | Full git history |
| AI draft from real session output | Magellan, BYO-key, direct to provider | Atlassian AI — no terminal context | Notion AI — no terminal context | Whatever you paste into ChatGPT |
| Per-Space audit on every edit | Yes — actor + timestamp; CSV export (Team+) | Audit on Premium / Enterprise plans | Audit on Enterprise plan | git blame / log |
| Native desktop, not a browser tab | macOS / Windows / Linux, signed + notarized | Browser | Browser + Electron app | Whatever editor you bring |
Before you install
The questions an SRE asks first.
Can I import my existing markdown runbooks?
Yes. Paste markdown directly into the Tiptap editor or drop in a .md file. Headings, code fences (with syntax highlighting), lists, tables, and inline links round-trip. Documents is a Team+ feature.
What about my Confluence pages?
There's no direct Confluence connector. Export the pages you care about to markdown (Confluence's built-in exporter, or a tool like confluence-markdown-exporter), then paste or file-import into ShellYard. Most teams find the export forces a useful pruning pass — the runbooks worth keeping are usually <10% of the wiki.
How does sharing a runbook with the team work?
Documents live in a Space. Put the runbook in a Shared Space (Team+ for Shared Spaces with Documents), and every member with read access sees it next to the connections it references. Role-gated: owner / admin / member, with module-level RBAC at Team+ so you can deny entire modules to specific groups.
Does Magellan ship my session output to ShellYard?
No. Magellan is BYO-key — you bring an Anthropic, OpenAI, Gemini, or local Ollama / LM Studio key. The prompt (and the attached session output) goes directly from your machine to your chosen provider. There's no ShellYard cloud component in the AI request path. Local providers keep AI traffic on your laptop.
How long is document version history kept?
Team plan: 90-day version history with side-by-side diff viewer. Enterprise: unlimited version history (subject to the per-Space byte cap). Every save is a version; every edit lands in audit with actor and timestamp.
macOS, Windows, Linux?
All three. Signed and notarized on macOS (Apple Developer ID). Authenticode-signed on Windows via Azure Trusted Signing. .deb / .rpm / AppImage on Linux. ~120 MiB install.
Write your next runbook IN the incident, not after it.
Install. Open the connection. Run the commands you already know. Select the output that matters, click Save as runbook, and you have a doc grounded in real session evidence — living next to the system it describes.
Free forever · No credit card · Versioned docs on Team+