Remote Machines and Data Sources

Remote Machines and Data Sources

Remote Data Sources let one CCAM instance mirror Claude and/or Codex history from SSH-accessible machines. CCAM uses the host's SSH configuration and credentials; it does not store passwords.

When to use which collection mode

Need	Best fit
Near-live events from a host that can reach CCAM	Authenticated remote hooks
Periodic history from a host CCAM can reach by SSH	Remote Data Source
One-time archive or disconnected machine	History import

Hooks and remote sources can complement each other, but avoid unintentionally collecting the same session twice through differently identified paths.

Prerequisites

• Key-based SSH works non-interactively from the CCAM host.
• The SSH host key is already trusted through an intentional process.
• The account can read the required provider transcript directories.
• Remote Claude and/or Codex home paths are known if non-default.
• Network policy permits SSH without opening unrelated services.

Add and test

Use Settings → Remote Data Sources or:

npx ccam remote-sources add --help
npx ccam remote-sources list

Add using a user@host destination or SSH config alias, then run the connection test and an explicit sync. Use CLI help for the current flags rather than copying credentials into commands.

Understand health

Each provider is mirrored independently. A source can be healthy when either Claude or Codex data is available, so a Claude-only or Codex-only host is valid. New and re-enabled sources sync immediately; the default poll interval is 15 seconds.

Remote sessions cannot use this host's process-liveness probe. Their active/completed state is reconciled from advancing transcript evidence within DASHBOARD_REMOTE_ACTIVE_WINDOW_MS (10 minutes by default). Slow links or long idle turns may justify a deliberate adjustment.

Safe removal

Deleting a source retains imported sessions by default. Purge is separate and irreversible:

npx ccam remote-sources rm <id> --purge --confirm PURGE_REMOTE_SOURCE_DATA

Use purge only after confirming source identity, scope, and backup. A disabled source is a safer first step during investigation.

Troubleshooting order

1. Verify raw ssh <alias> works as the CCAM service user.
2. Use the source's Test action.
3. Check provider-specific status and error text.
4. Confirm remote home paths and read permissions.
5. Check sync timeout and server logs.
6. Verify imported session source and newest transcript timestamp.

Recipe: Monitor Multiple Machines.