---
name: install-hermes-on-old-macos
description: Install Hermes Agent on old macOS (10.13 High Sierra) without Xcode, Homebrew, or dev tools. ZIP + uv bypass Xcode dependency entirely.
---

# Installing Hermes Agent on Old macOS (no Xcode)

## Context
Old Macs (2015 MacBook Air, High Sierra 10.13) can't install Xcode CLT — the popup appears but fails silently. This blocks git clone, nvm, and Homebrew which all need Xcode.

## Working Strategy
The key insight: the **uv** package manager installs without Xcode and can install Python too. So the approach is:

1. **Get the code**: Download a ZIP from GitHub instead of git clone
2. **Python + uv**: Bootstrap from the Hernes install script — it handles uv and Python 3.11 without Xcode
3. **Dependencies**: uv sync installs all Python packages in the project dir
4. **Launch**: symlink the hermes binary + PATH setup

## Step by step approach

### Phase 1 — Bootstrap
Run the official install script. It will succeed at installing uv and Python 3.11 but then fail at the git clone step (no Xcode). That's expected and fine.

### Phase 2 — Manual code download
Download the repository as a ZIP archive via curl. Extract into ~/.hermes/ and rename the folder to hermes-agent.

### Phase 3 — Python dependencies
cd into ~/.hermes/hermes-agent and run uv sync. This installs all Python dependencies (yaml, etc.). A .venv directory will be created or already exists.

Then install the package itself in editable mode so the `hermes` entry point is registered:
```bash
uv pip install -e .
```

**⚠️ Gotcha:** `uv sync` alone installs dependencies but does NOT make the `hermes` CLI command work — it only resolves packages. Without `uv pip install -e .`, running `hermes` will fail with `ModuleNotFoundError: No module named 'yaml'` because the system python is used instead of the venv python. Always run both commands.

### Phase 4 — Symlink & Shell config
Create a symlink so `hermes` is findable from anywhere:
```bash
ln -s ~/.hermes/hermes-agent/hermes ~/.local/bin/hermes
```

Add to ~/.zshrc:
- `export PATH="$HOME/.local/bin:$PATH"`
- `export HERMES_HOME="$HOME/.hermes/hermes-agent"`

### Phase 5 — Clean start (optional)
If Hermes was previously run and failed, its configs may be in a broken state. Wipe them to start fresh:
```bash
rm -rf ~/.config/hermes ~/.local/share/hermes ~/.cache/hermes
```

### Phase 6 — Launch

**⚠️ On High Sierra, `hermes` CLI command may still fail** with `ModuleNotFoundError: No module named 'yaml'` because the symlink resolves to system Python (which lacks the venv's yaml). The **reliable launch method** is always:

```bash
cd ~/.hermes/hermes-agent && .venv/bin/python hermes
```

This is the primary way to run Hermes on High Sierra. Symlink (`hermes` from anywhere) is unreliable — always use `.venv/bin/python hermes`.

First run will prompt for API key / run setup wizard.

### Verification
```bash
cd ~/.hermes/hermes-agent && .venv/bin/python hermes --help
```
Should show Hermes CLI help without errors.

## Known issues on High Sierra
- Old Node.js binary built for macOS 10.15+ crashes with a dyld symbol error (____chkstk_darwin). Remove it since Hermes CLI doesn't need Node — only Playwright does.
- Homebrew is unavailable for 10.13 — skip attempts.
- nvm also requires Xcode CLT — skip.
- ripgrep and ffmpeg can't be auto-installed; Hermes core works without them.

## Gateway setup (Telegram)
The setup wizard won't list Telegram unless `TELEGRAM_BOT_TOKEN` is in `.env`. Add it before running `setup gateway`.

## Memory migration to new instance
No CLI exists to programmatically set memory. To seed a new Hermes instance with user/project facts, present them as a chat prompt — the agent will use its memory tool to save each fact. This is the only reliable method.

## Anti-patterns (wasted time)
- xcode-select --install: pops up a dialog but CLT download fails
- Homebrew install script: requires CLT, fails
- nvm: requires CLT
- Git DMG installers: most are incompatible with 10.13
