Install

werbos runs entirely locally. The install is a clone, a venv, and an inference backend. No cloud account, no API key.

Prerequisites

1. Install werbos

From source (today’s path)

git clone https://github.com/jasonsutter87/werbos
cd werbos
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[siblings,dev]"

From PyPI (Sprint A.5 day 5)

Wheel-ready since 2026-05-09. Once siblings publish:

pip install werbos

The wheel bundles the SPA dist + all packaged personas, so --persona-name html, the React UI, and werbos serve all work out of the box without a source clone.

The siblings extra pulls in pitts (agent loop), pfm (archive format), mcculloch (eval), partyparrot (live wire), and the five Phase 2 orchestration siblings (observe, watchtower, warden, beacon, watchtower-ui). dev pulls pytest etc.

3. Pick a backend

Ollama (works everywhere)

brew install ollama          # macOS; or follow https://ollama.com for other OS
ollama pull llama3.1:8b-instruct-q4_K_M

mlx-lm (Apple Silicon only — faster + adapter support)

pip install ".[mlx]"
# the model downloads on first run

4. Confirm

werbos --help                # full subcommand list
werbos                       # bare invocation drops into chat REPL

You should see you> and be able to chat. Type :q to quit.

5. (Optional) UI

The React frontend lives in werbos/ui/ and proxies to a running werbos serve:

# terminal 1
werbos serve

# terminal 2
cd werbos/ui
npm install
npm run dev
# open http://localhost:5173

Where things land

After your first chat, the layout is:

~/werbos/
├── chats/             # PFM archives (one .pfm per chat session)
├── code/              # archives from `werbos code` runs
├── memory/            # cross-session memory (loaded into every prompt)
├── adapters/          # LoRA adapters (after you train one)
├── personas/          # persona files (foundation, role, mode)
├── skills/            # werbos-side skills (separate from ~/.claude/skills/)
└── benchmarks/        # JSON bench reports

You don’t have to create these — werbos creates them on demand. The home dir is your data dir; the cloned repo is the engine.

Verify the install

werbos doctor

Five concurrent checks (Ollama daemon, expected models pulled, sibling-SHA pinning, venv-editable installs, tailscale state) print a green/red checklist. Exit-1 on any FAIL so shell glue can branch on it. Details on the doctor page.

Bootstrap your data dir

werbos init (Sprint A.5 day 2) scaffolds your operator data dir on a fresh machine:

werbos init                       # creates ~/werbos/{chats,images,personas,skills,tasks}/
                                  # writes a templated user.md
                                  # probes Ollama at localhost:11434
                                  # prints actionable hints if anything's missing

# Override the data dir if you want it elsewhere:
werbos init --data-dir ~/my-werbos

# CI mode — fail loudly if Ollama isn't reachable:
werbos init --strict

# Re-run is idempotent (adds anything missing without clobbering).
# --force overwrites your user.md (default is preserve).
werbos init --force

What lands:

• ~/werbos/user.md — six-section operator profile template. ContextBuilder hydrates this into every session AFTER the persona, BEFORE history. A KIND_USER_PROFILE_LOADED event records {path, sha256, byte_size} per session — metadata only, never the body.
• ~/werbos/personas/default.md — copy of the bundled default persona, ready for you to customize.
• The standard subdirs — chats/, images/, skills/, tasks/.

Bootstrap a project (per-repo context)

For any repo where you want werbos to know the project-level context (sibling-repo relationships, build/test commands, naming conventions), drop a .werbos.md in the project root:

cd ~/code/my-project
werbos init project        # K.1 project flow: scans cwd, asks 3 questions, writes .werbos.md

Werbos picks up .werbos.md automatically every time you run werbos chat or werbos serve from anywhere inside that tree. See project context for the full surface.

Troubleshooting

• werbos: command not found — the venv isn’t on your PATH. Either activate the venv (source .venv/bin/activate) or alias the binary in your shell rc: alias werbos="$HOME/path/to/.venv/bin/werbos".
• Connection refused on Ollama — the daemon isn’t running. brew services start ollama or ollama serve in another terminal. werbos doctor surfaces this before you start a chat.
• OOM on M1 8GB during training — you’re trying to train an 8B model. Drop to 3B (mlx-community/Llama-3.2-3B-Instruct-4bit). The 8B fits for inference, not training, on 8GB.

Next

• Doctor — verify install, diagnose chat issues
• Personas — the voice / character / Tom / named-persona ladder
• Chat surfaces — every flag and slash in the REPL
• Vision — /see slash for screen capture + --vision-model
• Skills — the self-modifying skill registry
• Project context — per-repo .werbos.md
• How to train — turn your data into an adapter
• How to nudge — the dogfood loop that improves the model