NoteCove NoteCove

Set Up a Headless Remote Daemon

notecove serve --install-headless installs a full NoteCove daemon on a remote machine. The daemon operates completely independently — creating notes, reading tasks, opening files — even when there’s no network connection. When your Mac is reachable, changes sync bidirectionally with sub-second latency in the Mac-to-remote direction.

This is the right setup when you have a remote Linux server or Mac mini running Claude Code or other long-lived agent sessions and you need the agent to read your latest notes reliably, even after you’ve edited them on your Mac.

How it differs from notecove serve

notecove serve --sshHeadless daemon
Works when disconnectedNo — CLI dies when tunnel dropsYes — full read/write locally
Sync when connectedInstant (socket-forwarded)Near real-time (< 500 ms Mac → remote)
Remote stores dataNoYes (local copy of your SD)
Setup complexityLowModerate (one-time)

Use notecove serve for occasional or short-lived remote access. Use the headless daemon for permanent remote machines.

Prerequisites

  • NoteCove desktop app running on your Mac
  • SSH access to the remote machine (key-based auth recommended)
  • The remote is a Linux (x64 or arm64) or macOS machine (e.g. a Mac mini)

Step 1 — Install the daemon

Run this on your Mac:

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

The remote machine only needs SSH connectivity — it never contacts the internet directly. NoteCove downloads the release on your Mac and transfers it to the remote over SSH.

NoteCove will:

  1. Detect the remote platform (uname -s + uname -m)
  2. Download the NoteCove release for that platform (cached in ~/.local/lib/notecove-releases/ for reuse)
  3. Upload the binary to the remote
  4. Copy your auth config to the remote (same as --with-auth)
  5. Bootstrap the remote with a full copy of your Space data via rsync
  6. Install and start a systemd service (Linux) or launchd agent (macOS) so the daemon auto-starts on reboot
  7. Print the command to start the sync link
Detecting remote platform...
remote is Linux/arm64

Downloading NoteCove 1.2.3 for linux-arm64... (cached)
Uploading to user@remotehost...
✓ Binary installed at ~/.notecove.d/notecove-desktop

Copying auth config...
✓ Auth config installed

Bootstrapping Space data (this may take a moment)...
✓ Space synced

Installing systemd service...
✓ Service enabled and started

Ready. Start the sync link on your Mac:
  notecove link --ssh user@remotehost

Press Ctrl+C to exit.

The daemon is now running on the remote. The remote CLI can create, read, and update notes and tasks immediately, entirely from its local copy.

Step 2 — Start the sync link

On your Mac, start the long-running sync process:

notecove link --ssh user@remotehost

This keeps a bidirectional sync channel open between your Mac and the remote. Run it in a tmux or screen session so it persists when you close your terminal:

tmux new-session -d -s nc-link 'notecove link --ssh user@remotehost'

notecove link reconnects automatically when connections drop — Mac sleep, network blips, SSH timeouts. You only need to start it once per Mac session (or after a Mac reboot).

Linking multiple remotes at once

If you have several remote machines, list them all on the same command:

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

The link process maintains one independent connection per remote. Each remote syncs in parallel.

Step 3 — Use the CLI on the remote

SSH into the remote and use the CLI normally:

notecove note show "Sprint Plan"
notecove task create "Investigate the auth bug" --project BACK
notecove note create --title "Agent session 2026-05-24"

The daemon serves all CLI requests from its local copy. No network needed.

Opening a note on your Mac

notecove open <noteId>

When the sync link is active, this opens the note in your Mac’s desktop app — even though the command ran on the remote.

Getting the latest version of a note

If you just edited a note on your Mac and need the agent to see the changes immediately:

notecove note show <noteId> --fresh

--fresh does a synchronous pull from the Mac before returning — useful when sub-second freshness is critical. Without --fresh, the note is typically updated within 500 ms of your Mac edit; in practice the race almost never matters since switching from the NoteCove app to a terminal takes longer than that.

What happens when the connection drops

The remote daemon keeps working with its local data. Notes and tasks you create on the remote accumulate locally. notecove link detects the dead connection via heartbeat (ping/pong every 10 s; declared dead after 30 s) and retries automatically with exponential backoff — 5 s, 10 s, 20 s, 40 s, up to 60 s between attempts. When the connection comes back, both sides exchange only the changes since the last sync — no full resync.

You don’t need to restart notecove link. This includes Mac sleep/wake, network blips, and SSH timeouts. Leave it running in tmux and forget it.

What happens when your Mac sleeps

The SSH connections drop. The remote daemon continues operating locally. When your Mac wakes and the network comes back up, notecove link reconnects automatically — typically within a few seconds. No action needed.

Daemon management on the remote

Check the daemon status (Linux)

systemctl --user status notecove-headless

Restart the daemon (Linux)

systemctl --user restart notecove-headless

View daemon logs (Linux)

journalctl --user -u notecove-headless -f

On macOS remotes, substitute launchctl equivalents.

Installing a local build (beta / pre-release testing)

If you want to test a build that hasn’t been officially released yet, use --binary to point --install-headless at a local file instead of downloading from the release server:

# Linux remote — point at an AppImage or unpacked directory
notecove serve --install-headless --ssh user@remotehost \
  --binary ./packages/desktop/dist/linux-arm64/notecove-1.2.3-arm64.AppImage

# macOS remote — point at a .app bundle
notecove serve --install-headless --ssh user@mac-mini \
  --binary ./packages/desktop/dist/mac-arm64/NoteCove.app

Everything else (SD bootstrap, auth config, service install) works identically. The binary is uploaded to the remote over SSH — no internet access needed on either machine.

Updating the daemon

When you update NoteCove on your Mac, re-run the install command to push the new version to the remote:

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

The command detects the version difference, downloads the new release on your Mac (or uses the cached copy if you’ve already installed the same version elsewhere), uploads it, and restarts the service. The remote never needs to contact the internet.

Switching from notecove serve

If you currently use notecove serve --ssh on a remote machine and want to switch to the headless daemon:

  1. Stop notecove serve (Ctrl+C)
  2. Run notecove serve --install-headless --ssh user@remotehost
  3. Start notecove link --ssh user@remotehost

Do not run both notecove serve and the headless daemon for the same profile on the same remote — the CLI will connect to whichever it discovers first, producing unpredictable behavior.