Remote & headless sessions

What runs where#

The remote host runs HarnessDaemon and the CLI. Your Mac runs the graphical app, and your local CLI can target the remote daemon with --host. Transport is an SSH tunnel forwarding the daemon’s control socket—not a public, unauthenticated TCP service.

The graphical app and Metal renderer are macOS-only. Linux support covers the daemon and CLI. Keep the two ends on compatible Harness versions.

Prepare the remote host#

Install a Swift 6.0-or-newer toolchain appropriate to the host, check out the public repository, and build the daemon and CLI:

git clone https://github.com/robzilla1738/harness-terminal.git harness
cd harness
swift build -c release
./.build/release/HarnessDaemon

The last command runs the daemon in that terminal. For long-lived hosting, arrange supervision with the host’s service manager; merely closing that shell is not a durable service setup. Make harness-cli available to non-interactive SSH commands on the host. In a second host terminal, harness-cli socket-path prints the actual socket path.

Add the host#

In the Mac app, open the sessions popover and choose Add Remote Host. Supply the SSH destination; Harness detects the socket and tests the connection. For CLI setup, replace me@devbox with your actual SSH destination:

harness-cli remote add --name devbox --ssh me@devbox \
  --socket "$(ssh me@devbox harness-cli socket-path)"
harness-cli remote list
harness-cli ping --host devbox

The remote account needs access to its own daemon socket. First confirm that a normal SSH connection to the destination succeeds.

Use your SSH options#

Pass an option and its value as separate --ssh-arg arguments. For example, using port 2222 requires that port both for socket discovery and for the registered connection:

harness-cli remote add --name devbox --ssh me@devbox \
  --socket "$(ssh -p 2222 me@devbox harness-cli socket-path)" \
  --ssh-arg -p --ssh-arg 2222

Supported options include -p for port, -i for identity file, and -J for a jump host. Prefer an SSH config host alias when it already captures your connection settings. Do not add untrusted forwarding or authentication options blindly.

Work against the remote daemon#

harness-cli ls --host devbox
harness-cli new-session --host devbox --cwd /home/me/Code
harness-cli capture-pane --host devbox --surface "logs"

Use a real absolute path on the remote host for --cwd. An unquoted ~ can expand in your local shell before Harness sends the command. Use a target returned by the remote ls command instead of assuming a local pane ID exists remotely.

Each remote host opens in its own app window alongside local work. SSH tunnels reconnect after a drop; reconnecting a client does not itself restart the remote daemon.

Remove a saved host#

harness-cli remote remove --name devbox

Removing a connection entry is different from deliberately terminating remote workloads. Manage those workloads on their host, and capture any diagnostics you need before killing sessions or restarting a daemon.

Reconnect and diagnose a host#

When SSH drops, Harness preserves the last screen with a connection notice and retries attaching to surviving work. Use Remote → host → Retry Connection or Connection Details. Diagnostics exclude credentials and terminal output.

A process must still exist on the host to be reattached. Sleep pauses local processes; it does not guarantee uninterrupted execution. New workspace actions on an older daemon can report that an update is required.