Remote Files

Read, annotate, and edit Markdown that lives on another machine — a remote developer desktop, a build box, a server you reach over SSH — without mounting a volume or syncing a folder.

Opening a remote file

Three ways in, all pointing at the same place:

• File → Open Remote… or ⌘⇧O. Type an SSH target — user@host:/path/to/notes.md — and press Open.
• A mindle://ssh link. From a terminal on your Mac, open 'mindle://ssh/user@host/path/to/notes.md' hands the file straight to Mindle. Handy from scripts or a shell on the remote box itself.
• An agent. Over MCP, open_file accepts the same user@host:/path form as a local path, so a collaborator working on the remote machine can ask Mindle to open what it's looking at. See Agents.

A remote tab wears a small network glyph, and a ↻ button sits in the toolbar to re-fetch on demand.

It uses your SSH, not Mindle's

Mindle shells out to the ssh and scp already on your Mac. That means your ~/.ssh/config host aliases, agent keys, known_hosts, and ProxyJump all apply exactly as they do at the command line — Mindle never sees or stores a credential.

Connections are non-interactive (BatchMode) and fail fast: key or agent authentication just works, and a host that would prompt for a password gives you a clear error instead of hanging. If scp user@host:/path . works in your terminal, Open Remote… works.

How it works

On open, Mindle fetches the file to a local cache copy and runs the entire normal pipeline on that copy — the markdown renderer, the editor, diff-on-reload, annotations. Nothing in the reader knows or cares that the file came from elsewhere. SSH only touches three edges: open, save, and refresh.

The cache copy lives under ~/Library/Application Support/Mindle/ssh-cache/, keyed to the remote target. Re-opening the same target re-activates the existing tab instead of fetching again.

Editing and saving

Edit a remote file exactly like a local one (⌘E; see Editor). Save writes your change to the local copy and then pushes it back over SSH, uploading to a temporary file and renaming it into place — so a dropped connection can never leave a half-written file on the far end.

The local copy is always authoritative. If the push fails — host down, permission denied — your edit is safe locally and Mindle tells you the push didn't land, rather than pretending it did.

Refreshing

Remote tabs don't poll — there's no background SSH chatter while you read. When you want the latest, press ↻ (saving also re-checks). Mindle re-fetches and, if the file changed on the far end, shows the same track-changes overlay you'd get for a local file edited underneath you, so you can review what moved before accepting it. See Reading for the diff overlay.

Annotations

Annotations on a remote file are stored on your Mac, in a sidecar keyed to the remote target — so they persist across sessions and re-opens, exactly like local annotations. See Annotations.

For now they're local to your machine: a colleague opening the same remote file in their own Mindle won't see your notes. Shared, co-located annotations are a separate piece of work.

Scope

Remote support is deliberately narrow — it adds a transport, not a sync engine.

• Manual refresh, not live. No polling, no watching the remote file. You pull updates with ↻.
• Annotations stay local. Keyed to the target, on your machine, not shared between people yet.
• Key/agent auth. Password-only hosts aren't supported — set up a key or use your agent.
• Reading any type, editing text. Text-based files (Markdown, plain text) round-trip for editing; PDFs open read-only, same as locally.

← Back to Mindle