Ledge.sh: The Runnable Markdown Notebook for Developers

Ledge is a specialized notebook designed for DevOps and developers that transforms static Markdown into an interactive environment. It allows you to execute shell commands, write code, query SQL, and trigger AI prompts—all within your notes.

🚀 Quick Start: The Growth Workflow

Imagine a note titled "New subscriptions this week" with the following frontmatter: profile: stripe

Step 1: Fetch Data (Shell)

#growth
curl -sG https://api.stripe.com/v1/subscriptions \
  -u $STRIPE_KEY: \
  -d limit=100 -d created[gte]=$(date -v-7d +%s) > subs.json

jq -r '.data[].plan.nickname' subs.json | sort | uniq -c | sort -rn

Output: 24 Pro, 11 Team, and 3 Business since last Monday.

Step 2: Calculate MRR (Python)

import json
subs = json.load(open('subs.json'))['data']
mrr = sum(s['plan']['amount'] for s in subs) / 100
print(f"{len(subs)} subscriptions, +${mrr:,.0f} MRR")

Output: 38 new subscriptions, adding $2,682 in MRR.

Step 3: Verify via Database (SQL)

SELECT source, count(*) as upgrades 
FROM accounts 
WHERE upgraded_at = now() - interval '7 days' 
GROUP BY source 
ORDER BY upgrades DESC;

Output: The database agrees: 38 upgrades.

Step 4: Generate Report (AI Prompt)

prompt: Write this week's growth update from this note for #team

---

🛠️ Core Functionality & Installation

To run a block, simply press ⌘↩. The output streams directly beneath the code. Ledge works across your local machine, remote servers, or specific project environments.

Download Options

Quick Install (Ledge Server):

curl -fsSL https://ledge.sh/server.sh | sh

License: Apache-2.0 | Supported: macOS (Silicon), Linux, Windows 11 (WSL), iOS, Android.

---

⚙️ Technical Architecture

Ledge manages environments through a persistent state model.

Key Environment Features:

• Persistent State: Each note has its own shell. If you run cd or activate a virtualenv in one block, that state persists for the next.
• Terminal Drawer: Press ⇧⌘↩ to send a block to a dedicated terminal drawer for continuous interaction.
• Configuration: Use cwd: and env: in the frontmatter to define the starting directory and environment variables.

---

🌐 Remote Capabilities & Mobility

Server-Side Notes

You can point Ledge at a remote machine via SSH. This allows your desktop, phone, and other windows to access the same server simultaneously.

Security: Sign in using SSH keys or passwords stored in your system keychain. Backup: ledge backup creates hourly encrypted copies in S3-compatible storage.

Mobile Experience

Ledge on iPhone and iPad acts as a window into your server, supporting:

• Search, Tags, and Backlinks
• Daily Notes & Wikilinks
• Hardware keys (Secure Enclave) for authentication
• Terminal controls (^C, ^D, Esc, Arrow keys) above the keyboard

Remote Host Execution

By adding a host: line to the frontmatter, blocks execute over SSH on a specific machine.

• Safety: Mark blocks as confirm to require manual approval before execution.
• Compatibility: Supports ~/.ssh/config and 2FA.
• Interpreters: Python and Node blocks run on the host (configurable in Settings).

---

🖥️ Workspace & Secret Management

Layouts

• Split View: ⌘D (Vertical) or ⇧⌘D (Horizontal).
• Independence: Each pane maintains its own caret, scroll position, and streaming output.
• Persistence: Workspaces save and restore layouts automatically.

Handling Secrets

To keep sensitive data out of your notes, Ledge uses Profiles.

1. Create a dotenv file at ~/.config/ledge/profiles/deploy.env.
2. Reference it in frontmatter: profile: deploy.
3. Use envFile: .env for non-secret project variables. The built-in editor masks these values by default.

---

🤖 AI Integration (MCP)

Ledge includes an MCP (Model Context Protocol) server, allowing agents like Claude Code to interact with your notes.

Setup: claude mcp add ledge -- ledge

Agent Capabilities:

• Read, search, create, and edit notes.
• Reference notes by title (stable across renames).
• Execute blocks via ⌘↩ and stream replies.
• Delete notes $\rightarrow$ There is no delete tool for agents.
• Locked notes are strictly off-limits to agents.

---

🔒 Security & Maintenance

Note Locking

You can encrypt a note's body using a passphrase.

• Ciphertext: Sync services only see encrypted data.
• Privacy: Agents cannot access locked content.

Example: Release Management

Note: Release 2.5.0 cwd: ~/Projects/api

#release
git log --oneline v2.4.1..HEAD | head -3

Result:

• 9f31c22 storage: chunked uploads for assets $> 50\text{ MB}$
• 41b0a07 api: rate limit per token, not per IP
• c2ade19 fix: retry idempotent writes on 5xx