Setup guide

Everything you need to go from zero to a fully running Harvis instance — including Claude, Telegram, mobile sync, and the web dashboard.

Prerequisites

Software	Notes
Windows 10/11 (64-bit)	Already on your machine
WSL2	Run wsl --install in PowerShell as Admin
Docker Desktop	Enable the WSL2 backend during install
Git (Windows)	git-scm.com

Account	Purpose	Cost
GitHub	Vault backup + version history	Free
Anthropic / Claude	AI — requires Claude Max or Pro	Paid
Telegram	Mobile bot interface	Free

Verify Docker is ready before continuing:

docker run --rm hello-world

You should see "Hello from Docker!" — if so, you're good.

Installation steps

Get the infra repo

Create the project folder and clone the Harvis infrastructure repo:

mkdir C:\Users\<you>\Documents\Harvis cd C:\Users\<you>\Documents\Harvis git clone https://github.com/<infra-repo> .

The infra repo contains the Dockerfile, docker-compose.yml, scripts/, config/, and start.ps1.

Get the AI tool layer

Clone claude-obsidian into the project folder. The compose file bind-mounts it read-only into the container.

git clone https://github.com/AgriciDaniel/claude-obsidian

Create your vault repository on GitHub

Go to github.com → New repository
Name it harvis_vault (or anything you like)
Set it to Private
Do not initialise with a README — the container does this on first start
Copy the SSH remote URL: git@github.com:<you>/harvis_vault.git

Configure the environment

Copy the example config and fill in your details:

cp .env.example .env

# Your identity for git commits GIT_USER_NAME=Your Name GIT_USER_EMAIL=you@example.com # SSH remote for your vault repo (from Step 3) VAULT_REMOTE=git@github.com:<you>/harvis_vault.git # Obsidian version — check obsidian.md/download for latest OBSIDIAN_VERSION=1.8.10 # Syncthing version SYNCTHING_VERSION=1.29.2

Never commit .env — it's in .gitignore by default.

Build and start the container

docker compose up -d --build

The first build takes 5–15 minutes. Watch the logs:

docker compose logs -f brain

When ready, all 8 processes should show RUNNING:

docker compose exec brain supervisorctl status claude RUNNING pid 96, uptime 0:05:00 claude-cred-watchdog RUNNING pid 101, uptime 0:05:00 gitwatch RUNNING pid 94, uptime 0:05:00 harvis-dashboard RUNNING pid 105, uptime 0:05:00 obsidian RUNNING pid 92, uptime 0:05:00 syncthing RUNNING pid 93, uptime 0:05:00 telegram-bridge RUNNING pid 103, uptime 0:05:00 xvfb RUNNING pid 91, uptime 0:05:00

Add the SSH deploy key to GitHub

The container generates an ed25519 key on first start. Get the public key:

cat "C:\Users\<you>\Documents\Harvis\data\ssh\id_ed25519.pub"

Go to github.com/<you>/harvis_vault → Settings → Deploy keys
Click Add deploy key
Title: Harvis, paste the public key, tick Allow write access

Verify it works:

docker compose exec brain bash -c 'ssh -T git@github.com'

Expected: Hi <you>/harvis_vault! You've successfully authenticated...

Log in to Claude

Attach to the Claude tmux session:

docker compose exec brain gosu brain tmux -S /tmp/brain-tmux.sock attach -t brain

If Claude is waiting for login, type /login and follow the OAuth flow in your browser. Detach when done with Ctrl-b d.

Set up the Telegram bot (optional)

Message @BotFather on Telegram → /newbot → copy the token
Add to /vault/.harvis/config.env:
TELEGRAM_BOT_TOKEN=<your token>
Restart the bridge:
docker compose exec brain supervisorctl restart telegram-bridge
Message your bot anything — it replies in discovery mode with your chat ID. Add it to config.env:
TELEGRAM_ALLOWED_CHAT_ID=<your chat ID>
Restart the bridge again, then send /status to confirm.

Confirm the dashboard is running

Open http://localhost:3000 in your browser. You should see the Harvis Dashboard with Tasks, Projects, Wiki, and Chat tabs.

If it's not loading:

docker compose exec brain supervisorctl restart harvis-dashboard

Set up Syncthing for mobile notes (optional)

Open the Syncthing web UI at http://127.0.0.1:8384
Install Syncthing on your phone (F-Droid / Möbius Sync for iOS)
Get your phone's Device ID: Syncthing app → menu → Show Device ID
In the PC Syncthing UI → Add Remote Device → paste the phone's Device ID
Accept the pairing on your phone, then share the Default Folder (your vault)
Install Obsidian Mobile → open the synced folder as a vault

Changes you make on your phone sync to the container in seconds. Changes Claude makes in the container sync back to your phone in seconds. The full loop takes under a minute.

Configure auto-start after reboot

Run start.ps1 after every reboot to bring Docker Desktop and the container back up automatically:

.\start.ps1

If Windows blocks script execution: powershell -ExecutionPolicy Bypass -File .\start.ps1

Verification checklist

# All 8 processes running docker compose exec brain supervisorctl status # Vault is pushing to GitHub docker compose exec brain bash -c 'gosu brain git -C /vault log --oneline -5' # SSH auth works docker compose exec brain bash -c 'ssh -T git@github.com' # Claude session alive docker compose exec brain gosu brain tmux -S /tmp/brain-tmux.sock has-session -t brain && echo "Claude: OK" # Telegram — send /status to your bot # Dashboard — open http://localhost:3000

Troubleshooting

Container won't start / keeps restarting

Most common on first start — WSL2 bind-mount timing bug. Force recreate:

docker compose up -d --force-recreate

Claude says it has no credentials

Attach and run /login, then clear the stale flag:

docker compose exec brain gosu brain tmux -S /tmp/brain-tmux.sock attach -t brain # Inside: /login docker compose exec brain bash -c 'rm -f /var/log/claude-cred-stale.flag'

Vault not pushing to GitHub

The deploy key may have been removed. Test SSH auth:

docker compose exec brain bash -c 'ssh -T git@github.com'

Telegram bot not responding

Check the bridge status and logs:

docker compose exec brain supervisorctl status telegram-bridge docker compose exec brain tail -50 /vault/.harvis/bridge.log

Dashboard shows blank

Restart the dashboard process:

docker compose exec brain supervisorctl restart harvis-dashboard

How to use Harvis

Daily workflows, slash commands, example prompts, and note organisation tips.

Read the overview →

Dashboard

Already set up? Sign in and go to your dashboard.