> ## Documentation Index
> Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote audits

> Audit OpenClaw data on SSH hosts or Railway services from your local machine.

Use remote audits when OpenClaw is not running on the same machine where you invoke Xerg.

Hermes support is local-only. `--remote`, `--railway`, and `--remote-config` currently target OpenClaw sources only.

Use only one of `--remote`, `--remote-config`, or `--railway` in a single command.

Examples use `npx @xerg/cli@latest`. If you installed the CLI globally, substitute `xerg`.

## SSH audits

Prerequisites:

* `ssh` on your `PATH`
* `rsync` on your `PATH` for the fastest transfer path
* access to the target host

Basic audit:

```bash theme={null}
npx @xerg/cli@latest audit --remote deploy@prod.example.com
```

Custom remote paths:

```bash theme={null}
npx @xerg/cli@latest audit \
  --remote deploy@prod.example.com \
  --remote-log-file /var/log/openclaw \
  --remote-sessions-dir /srv/openclaw/sessions \
  --since 24h
```

Doctor first:

```bash theme={null}
npx @xerg/cli@latest doctor --remote deploy@prod.example.com
```

Notes:

* `--remote` accepts `user@host` or `user@host:port`
* if `rsync` is unavailable or fails, Xerg falls back to `tar` over SSH
* `--keep-remote-files` keeps pulled data in `~/.xerg/remote-cache/<source-name>/` instead of cleaning up a temporary directory

## Railway audits

Prerequisites:

* the `railway` CLI on your `PATH`
* a Railway login that can reach the target project or the service linked to the current working directory

Use the linked service for the current directory:

```bash theme={null}
npx @xerg/cli@latest audit --railway
```

Linked Railway mode is cwd-dependent. Xerg uses whichever Railway service is linked in the directory where you run the command.

If the current directory is linked to a database, sidecar, or another non-OpenClaw service, re-run `railway link` in that directory and choose the OpenClaw app service.

Target a specific service:

```bash theme={null}
npx @xerg/cli@latest audit \
  --railway \
  --project <project-id> \
  --environment <environment-id> \
  --service <service-id>
```

Custom remote paths:

```bash theme={null}
npx @xerg/cli@latest audit \
  --railway \
  --project <project-id> \
  --environment <environment-id> \
  --service <service-id> \
  --remote-log-file /tmp/openclaw \
  --remote-sessions-dir /data/.clawdbot/agents/main/sessions
```

By default, Railway audits check `/tmp/openclaw` for gateway logs and `~/.openclaw/agents` for session files. Railway also checks `/data/.clawdbot/agents/main/sessions` as an alternate session location when the default session directory is empty.

Use explicit `--project`, `--environment`, and `--service` values for CI, automation, or any workflow where you want the target to stay stable regardless of the current directory.

If Xerg cannot reach the linked service for the current directory, run `railway login` first if needed, then run `railway link` in that directory and choose the OpenClaw app service.

If you pass explicit Railway IDs and Xerg still cannot reach the service, verify that the provided `--project`, `--environment`, and `--service` values point at the OpenClaw app service.

If the target Railway service is reachable but Xerg still reports no OpenClaw data, verify that you selected the OpenClaw app service rather than a database or sidecar. If the app writes data to different paths, override them with `--remote-log-file` and `--remote-sessions-dir`.

## Multi-source audits with `--remote-config`

Use `--remote-config` when you want one command to pull several SSH or Railway sources.

Example config:

```json theme={null}
{
  "remotes": [
    {
      "name": "prod",
      "host": "deploy@prod.example.com",
      "identityFile": "~/.ssh/prod_ed25519",
      "logFile": "/tmp/openclaw",
      "sessionsDir": "~/.openclaw/agents"
    },
    {
      "name": "worker",
      "transport": "ssh",
      "host": "deploy@worker.example.com:2222"
    },
    {
      "name": "railway-api",
      "transport": "railway",
      "railway": {
        "projectId": "prj_123",
        "environmentId": "env_123",
        "serviceId": "svc_123"
      },
      "sessionsDir": "/data/.clawdbot/agents/main/sessions"
    }
  ]
}
```

Run it:

```bash theme={null}
npx @xerg/cli@latest audit --remote-config ./remotes.json
```

Behavior to know:

* `transport` defaults to `ssh`
* each entry needs a `name`
* Railway entries require `projectId`, `environmentId`, and `serviceId`
* plain terminal or Markdown output prints one section per source
* `--json` returns a top-level `{ "sources": [...] }` object when more than one source succeeds
* if some sources fail, Xerg continues with the sources it could pull and prints warnings for the ones it could not reach

## Remote comparisons

Remote and Railway audits can still use `--compare`, but the baseline lives in the local JSON snapshot store on the machine running Xerg. Xerg pulls the remote telemetry to your machine and analyzes it locally. It does not analyze the data on the SSH host or on Railway itself. Re-run the same target with the same effective remote paths if you want clean before and after deltas.