NoteCove NoteCove

Remote CLI Access

NoteCove offers two ways to use the CLI on a remote machine:

ModeBest for
notecove serve --sshOccasional or short-lived access; simplest setup; requires Mac desktop running and connected
Headless daemonPermanent remote machines; works offline; near-real-time sync when connected

notecove serve — SSH-forwarded tunnel

notecove serve projects your local NoteCove profile to a remote machine over SSH, so the CLI on the remote works exactly as if the desktop app were running there.

How It Works

The command establishes an SSH Unix socket forward (-R) from the remote machine to your local desktop app, then writes a registry entry on the remote. The remote CLI connects through the forwarded socket — completely unaware it’s talking to a Mac across the network.

When you stop the tunnel (Ctrl+C), the registry entry is cleaned up automatically.

When to Use This

  • You’re SSH’d into a server and want to use notecove commands there
  • You’re running an AI assistant (Claude Code, etc.) on a remote machine and want it to have NoteCove access
  • You want to use the CLI from a Docker container or VM

Step-by-Step

Prerequisites: NoteCove desktop app running locally; notecove CLI installed on the remote; SSH access (key-based auth recommended); OpenSSH 6.7+.

Step 1 — Start the tunnel (on your Mac):

notecove serve --ssh user@remotehost

NoteCove connects, establishes the socket forward, and prints the init command for the remote.

Step 2 — Initialize access on the remote:

notecove init --profile abc123 --project MYPROJ

Approve the request in your local NoteCove desktop app.

Step 3 — Use the CLI on the remote normally. All commands go through the forwarded socket.

Step 4 — Stop: Press Ctrl+C in the notecove serve terminal.

Extra SSH Options

notecove serve --ssh user@remotehost --ssh-opts "-i ~/.ssh/mykey -p 2222"

Command Reference

FlagDescription
--ssh <user@host>Remote host to connect to (enables automated SSH mode)
--ssh-opts <opts>Extra SSH options passed through to the ssh command

Headless daemon — persistent, autonomous remote

notecove serve --install-headless installs a full NoteCove daemon on the remote that runs independently — with its own local copy of your Space data. The daemon operates without any connection to your Mac. When the Mac is reachable, changes sync bidirectionally with sub-second Mac-to-remote latency.

When to Use This

  • The remote machine runs long-lived agent sessions (Claude Code, etc.) that must keep working when your Mac is asleep or offline
  • You need the agent to read your latest note edits with minimal delay after you type continue
  • You have multiple remote machines that all need NoteCove access concurrently

How It Works

The same notecove-desktop binary used for the Mac desktop app runs in headless mode on the remote (NOTECOVE_HEADLESS=1). It keeps a local copy of your Space data, serves all CLI requests locally, and syncs with your Mac via notecove link when connected.

notecove link runs on your Mac as a long-lived process. It maintains one SSH connection per remote and pushes CRDT changes bidirectionally. When your Mac desktop emits a “note modified” event, notecove link delivers the changes to all connected remotes within ~100–500 ms.

Quick Start

Install on the remote (run on your Mac):

notecove serve --install-headless --ssh user@remotehost

Start the sync link (on your Mac — run once; auto-reconnects on sleep/wake):

notecove link --ssh user@remotehost

Multiple remotes:

notecove link --ssh user@vm1 --ssh user@mac-mini

Get the latest version of a note before the agent reads it:

notecove note show <noteId> --fresh

For full setup instructions, see Set Up a Headless Remote Daemon.