# beaver-agent

My real beaver-gateway setup (paired with the protocol from beaver.kotikot.com).

Uses Claude Code and Raycast subscriptions for agents, has some MCPs set up. You can use this as-is or modify to match your needs (config.py).

## Requirements

- Docker + Docker Compose
- Obsidian Sync (for `obsidian-headless`)
- claude.ai sub
- raycast sub
- Firefly III and its PAT

## First launch

### 1. Create `.env` and `raycast.json`

```bash
cp .env.example .env
# fill CHANGE-ME
nvim .env

# build raycast config on your mac (beta by default, consider checking raycast-api for instructions)
raycast-api init

# copy config.json to your deployment server

docker compose up -d
```

### 2. Set up Obsidian Sync

```bash
docker exec -it beaver-obsidian ob login
docker exec -it beaver-obsidian ob sync-setup --vault "yourvault"
docker restart beaver-obsidian
```

Check:

```bash
docker exec beaver-obsidian ls /vault
```

Only markdown is synced by default. To sync everything:

```bash
docker exec beaver-obsidian ob sync-config \
  --file-types image,audio,video,pdf,unsupported
docker restart beaver-obsidian
```

### 3. Set up claude

```bash
docker exec -it beaver-gateway claude /login
docker exec -it beaver-gateway bash -c 'cd /vault && claude --dangerously-skip-permissions --model claude-opus-4-7'
```

Click through every dialog, then `/exit` or Ctrl+C.

### 4. Mint a token

Open admin at `http://localhost:62992` (or `https://<DOMAIN>/admin/` if Caddy), sign in with `ADMIN_USER` / `ADMIN_PASS`, go to **Tokens → Create**, scope `*` for first run.

### 5. Smoke test

```bash
docker exec beaver-gateway ls /vault | head
docker logs beaver-gateway | grep -i "agent registered"

curl http://localhost:62990/v1/models \
  -H "Authorization: Bearer <YOUR_TOKEN>"
```

## Where to plug things in

The admin dashboard renders ready-to-copy URLs and snippets for each of these

- any Anthropic client: `http://localhost:62990` or `https://<DOMAIN>/anthropic`, model = agent name (`beaver-opus-high` etc)
- MCP clients (Claude Desktop, Raycast extension): just find in admin
- Obsidian companion plugin: paste the dashboard's **plugin base** (`http://localhost:62993` raw, or `https://<DOMAIN>/md` behind Caddy) into the plugin's "Base URL" setting
- **Admin UI:** `http://localhost:62992` or `https://<DOMAIN>/admin`, login from `ADMIN_USER` / `ADMIN_PASS`

## Exposing to the internet

Reference config in `caddy`. Designed for: gateway on rpi, Caddy on a server with a public IP, wired through tailscale.

```bash
cd caddy
cp Caddyfile.example Caddyfile
cp .env.example .env   # only for cloudflare
# replace <DOMAIN>; point upstreams at wherever the gateway is reachable
docker compose up -d
```

Set `PUBLIC_BASE_URL=https://<DOMAIN>` in beaver-agent's `.env`. For per-subdomain layout, rewrite the Caddyfile and pass full `public_base_url=...` per frontend in `config.py`.

## Useful commands

```bash
# shell into the gateway container (claude CLI, bun, python with venv all live here)
docker exec -it beaver-gateway bash

# what obsidian-sync has pulled
docker exec beaver-obsidian ob status

# force a one-off sync (don't wait for the continuous tick)
docker exec beaver-obsidian ob sync

# per-service logs
docker compose logs -f gateway
docker compose logs -f obsidian-headless

# pull the latest beaver-gateway (when GATEWAY_REF=main)
docker compose build gateway && docker compose up -d gateway

# reload config.py without a full rebuild
docker compose restart gateway
```

## Gotchas

- **claude in the container doesn't see the vault** - `cwd=VAULT` in `config.py` resolves to `/vault` *inside* the container, not on the host. Don't change it.
- **gateway hangs on `JSONL file did not appear within 30s`** - claude's onboarding wasn't clicked through (see step 3). Re-enter interactively with `docker exec -it beaver-gateway ...`, click trust folder + bypass permissions, exit.