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

# Healthcheck

> Keeps your AI running smoothly. Watches for problems and fixes them automatically. Includes daily backups.

# Healthcheck

Keeps your AI running smoothly. Watches for problems, fixes what it can, and alerts you about the rest. Includes a daily backup system with verification.

Zero npm dependencies. Runs via macOS LaunchAgent.

## What It Does

Runs every 3 minutes and checks:

1. **Gateway process** ... is your AI's gateway running?
2. **HTTP probe** ... does the gateway respond to requests?
3. **File descriptors** ... is the gateway approaching system limits?
4. **Token usage** ... are any sessions near context window capacity?
5. **Memory health** (every 5th run) ... NULL embedding vectors, API key errors, session export freshness, memory capture errors

When something fails:

* **Auto-restart:** Restarts the gateway automatically (rate-limited so it doesn't loop)
* **AI alert:** Sends a message to your AI via the chat endpoint
* **iMessage fallback:** Direct iMessage to you if the AI is unreachable

## Install

```bash theme={null}
git clone https://github.com/wipcomputer/wip-healthcheck.git
cd wip-healthcheck
cp config.example.json config.json
# Edit config.json with your values
bash install.sh
```

This installs a LaunchAgent that runs the healthcheck every 3 minutes.

### Backup system (optional)

```bash theme={null}
bash install-backup.sh
```

This installs:

* A LaunchAgent that runs daily backups at midnight
* A scheduled job that verifies the backup at 00:30

## Configuration

Copy `config.example.json` to `config.json` and edit:

```json theme={null}
{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "token": ""
  },
  "escalation": {
    "escalationContact": "you@icloud.com",
    "model": "",
    "viaAgent": true,
    "cooldownMinutes": 15
  },
  "paths": {
    "openclawHome": "",
    "sessionExports": "",
    "backupRoot": "",
    "backupExpectedFiles": ["crystal.db", "context-embeddings.sqlite"]
  },
  "backup": {
    "retentionDays": 7,
    "sources": []
  }
}
```

### Key Fields

| Field                          | What                                                         | Default                           |
| ------------------------------ | ------------------------------------------------------------ | --------------------------------- |
| `gateway.token`                | Gateway auth token. Auto-read from `openclaw.json` if empty. | `""`                              |
| `escalation.escalationContact` | iMessage address for direct fallback alerts.                 | `""`                              |
| `escalation.viaAgent`          | Try alerting your AI before iMessage.                        | `true`                            |
| `paths.openclawHome`           | OpenClaw home folder.                                        | `$OPENCLAW_HOME` or `~/.openclaw` |
| `paths.backupRoot`             | Where daily backups go. Empty skips backup verification.     | `""`                              |
| `backup.retentionDays`         | Days of backups to keep.                                     | `7`                               |

### Backup Sources

Add custom backup sources to `backup.sources`:

```json theme={null}
{
  "backup": {
    "sources": [
      { "type": "file", "src": "/path/to/file.db", "name": "file.db" },
      { "type": "tar",  "src": "/path/to/directory", "name": "archive.tar" },
      { "type": "dir",  "src": "/path/to/dir", "name": "dir-copy" }
    ]
  }
}
```

Types: `file` (copy), `tar` (archive directory), `dir` (recursive copy).

If `sources` is empty, the backup script backs up core files automatically (crystal.db, context-embeddings.sqlite, main.sqlite, workspace, sessions, config).

## Manual Run

```bash theme={null}
node healthcheck.mjs       # run one check
bash backup.sh              # run one backup
bash verify-backup.sh       # verify today's backup
```

## Uninstall

```bash theme={null}
bash uninstall.sh           # removes healthcheck LaunchAgent
```

## Files

```
healthcheck.mjs         Main watchdog script
backup.sh               Daily backup script (config-driven)
backup-wrapper.mjs      Node wrapper for backup LaunchAgent
verify-backup.sh        Backup verification (scheduled)
config.json             Your config (not committed)
config.example.json     Config template
install.sh              Install healthcheck LaunchAgent
install-backup.sh       Install backup LaunchAgent + verify job
uninstall.sh            Remove healthcheck LaunchAgent
```

## Requirements

* Node.js (18+)
* macOS (uses LaunchAgent, iMessage, lsof)
* OpenClaw gateway running

## License

MIT