Documentation

How to set up and use ACTVT's agent session features

Remote Sessions

ACTVT can list the Claude Code and Codex CLI sessions running on your other machines, including headless Linux boxes, from your Mac. It connects over plain SSH, so there is no cloud service in between.

Remote Sessions is available on any paid tier (Basic or Premium) and during the free trial.

Install the CLI on each remote host

Run this on every machine you want to see sessions from:

Run on the remote host

curl -fsSL https://actvt.io/install-cli.sh | sh

Installs to ~/.local/bin/actvt-cli without needing sudo

Supports Linux arm64 and x86_64 as well as macOS

Macs already running Actvt.app can skip this step. The CLI ships inside the app bundle and is found automatically.

Set up SSH key authentication

ACTVT connects with BatchMode=yes, so password prompts are never shown. A host that asks for a password appears unreachable instead, which is why key-based auth is required.

Aliases from ~/.ssh/config work, so you can add hosts by their alias

Keys loaded via ssh-agent or the macOS keychain work from the app

Example ~/.ssh/config entry

# ~/.ssh/config
Host dgx
    HostName dgx-spark.example.ts.net
    User you
    IdentityFile ~/.ssh/id_ed25519

Enable Remote Sessions in the app

Open Settings → Agents → Remote Sessions and switch it on.

Online Tailscale peers (macOS and Linux) are discovered automatically and can be toggled individually

Add any other machine manually by hostname or SSH alias using the input at the bottom of the host list

Each host shows a reachability dot. Hosts that fail collapse into an "Unreachable (N)" group with the error for each one

Privacy & architecture

Nothing runs permanently on the remote machine. The CLI is invoked for each fetch (about every 60 seconds while the app is active), reads the session files, and exits

Remote data is held in memory only and is never written to your Mac's local metrics index

Remote rows carry references and summaries only. Token and cost numbers stay on each machine

Remote Transcripts

Use the picker row at the top of the sessions list to switch between All, This Mac, and each reachable host. All merges every machine into one chronological timeline, with a host badge on remote rows.

Reading a transcript

Click any remote row to open the full transcript. It is fetched on demand over SSH and rendered in the same viewer as local sessions, with PII masking running on your Mac. Like all remote data, it is held in memory only.

Remote transcripts need actvt-cli 0.2.0 or newer on the host. Settings shows a "CLI update available" badge when a host needs updating.

Resuming a session

Right-click a remote row and choose Resume in Terminal to reopen the session over SSH, or Copy resume command to run it in a terminal of your choice.

In the session browser

The full session browser (See All) lists All and each host under Machines. Remote rows are searchable by title, project, or branch. Remote listings are also available to MCP clients through the agent_remote_sessions tool.

Live Status

Session dots reflect the real state of the agent process, which the app checks periodically.

Fix flaky auth test

~/projects/app · main

Streaming a response

Pulsing green means the agent is streaming a response

Static green shows the CLI is alive but waiting for your input

Red marks a session that recently errored

No dot means the CLI has exited. Killed CLIs lose their dot within about 15 seconds

Toggle it in Settings → Agents → "Process-based live status". When it is off, or when the process check is inconclusive, dots fall back to the previous behavior based on file freshness.

Troubleshooting

Host shows as unreachable

Check that SSH key authentication works from your Mac (try ssh -o BatchMode=yes host true) and that actvt-cli is installed on the host. The exact error for each host is shown in Settings.

"Unexpected reply" from a host

The CLI on that host is out of date. Re-run the install one-liner to update it.

Neutral dot on a just-added host

This is normal. The dot stays neutral until the first fetch completes.