127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
# 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.
|