Bond — Local-First AI Assistant

Bond is a personal AI assistant that runs entirely on your machine. It connects to LLM providers of your choice (Anthropic, OpenAI, Ollama, etc.), manages conversations through a WebSocket gateway, and gives you a clean web UI — all without sending your data to third-party services.

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Frontend   │────▶│   Gateway    │────▶│   Backend    │────▶│ SpacetimeDB  │
│  (Next.js)   │     │  (WebSocket) │     │  (FastAPI)   │     │  (Database)  │
│  :18788      │     │  :18789      │     │  :18790      │     │  :18787      │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

git clone <your-repo-url> bond
cd bond

# Install all dependencies (Python, Gateway, Frontend, SpacetimeDB)
make install

This will:

• Check for the SpacetimeDB CLI (offers to install it if missing)
• Optionally start a local SpacetimeDB instance via Docker
• Install Python dependencies via uv sync
• Install Gateway dependencies via pnpm install
• Install Frontend dependencies via pnpm install

make setup

The wizard walks you through:

1. Pick your LLM provider — Anthropic, OpenAI, Google, DeepSeek, Groq, Mistral, Ollama, OpenRouter, xAI, Azure, Bedrock, LM Studio, or any OpenAI-compatible API
2. Choose a model — sensible defaults are suggested (e.g. claude-sonnet-4-20250514 for Anthropic)
3. Enter your API key — stored in an encrypted local vault (skipped for local providers like Ollama)

Configuration is saved to bond.json and ~/.bond/.

# Start SpacetimeDB via Docker (recommended)
make spacetimedb-up

Verify it's running:

make spacetimedb-health

make migrate

This applies the current Bond migrations and publishes the SpacetimeDB module. Bond operational state is stored in SpacetimeDB. SQLite should only be assumed for explicitly local or vector-storage use cases.

make dev

This starts all three services concurrently:

• Backend → http://localhost:18790
• Gateway → ws://localhost:18789
• Frontend → http://localhost:18788

Open http://localhost:18788 in your browser and start chatting.

make install && make setup && make spacetimedb-up && make migrate && make dev

Run everything in a single container:

docker compose up --build

This exposes the same three ports (18788, 18789, 18790) and manages data in a Docker volume.

For development with hot-reload:

docker compose -f docker-compose.dev.yml up

Primary configuration file — LLM provider, model, ports, SpacetimeDB connection:

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },
  "backend": { "host": "0.0.0.0", "port": 18790 },
  "gateway": { "host": "0.0.0.0", "port": 18789 },
  "frontend": { "port": 18788 },
  "spacetimedb": {
    "url": "http://localhost:18787",
    "module": "bond-core-v2"
  }
}

Optional overrides and secrets. See .env.example for all options:

cp .env.example .env

Key variables:

• SPACETIMEDB_TOKEN — Auth token for SpacetimeDB (auto-configured by setup)
• ANTHROPIC_API_KEY / OPENAI_API_KEY — API keys (prefer the vault via make setup)
• BOND_VAULT_KEY — Encryption key for the local vault (auto-generated if unset)

Bond's local data directory:

~/.bond/
├── data/          # Local worker/vector data only when explicitly configured
├── logs/          # Application logs
├── cache/         # LLM response cache, repo maps
├── workspace/     # Agent working directory
├── spacetimedb/   # SpacetimeDB data (Docker volume)
└── config.json    # Package manager preference

Switch providers anytime by re-running make setup or editing bond.json.

If you have a Claude Max or Pro subscription ($20–100/mo), you can use your subscription's OAuth token instead of paying per-API-call. This means unlimited usage (within subscription rate limits) at a flat monthly cost.

How to set it up:

1. Install Claude CLI (if you haven't already):

   npm install -g @anthropic-ai/claude-code

   Or run it once with npx @anthropic-ai/claude-code to trigger the OAuth flow.

2. Run claude once — it opens a browser for Anthropic login and creates ~/.claude/.credentials.json.

3. Run make setup and select Anthropic. When prompted for authentication method, choose "OAuth (Claude Max/Pro)" instead of entering an API key.

4. Bond auto-detects the credentials, refreshes tokens automatically, and injects the required headers — you don't need to manage anything.

Note: OAuth tokens require specific HTTP headers and a system prompt prefix for the Anthropic API. Bond handles all of this automatically via the gateway's OAuth module. Some models may have different rate limits under OAuth vs a standard API key.

Bond kills stale processes on startup, but if you still get conflicts:

lsof -ti :18788 :18789 :18790 | xargs kill -9

# Check if Docker is running
docker ps

# Try the simple compose (no network config)
make spacetimedb-simple-up

# Or start manually
docker run -d --name bond-spacetimedb -p 18787:3000 \
  -v ~/.bond/spacetimedb:/var/lib/spacetimedb \
  clockworklabs/spacetime:v2.0.2 start

# Install golang-migrate with SQLite support
make install-migrate

# Check current migration version
make migrate-version

# Roll back one migration
make migrate-down

Re-run the setup wizard:

make setup

Or set the key directly in .env:

echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env

cd frontend && pnpm install && pnpm build

bond/
├── backend/              # Python FastAPI backend
│   ├── app/
│   │   ├── agent/        # LLM orchestration, tools, memory
│   │   ├── api/          # REST API routes
│   │   ├── core/         # Vault, database, config
│   │   ├── sandbox/      # Code execution sandboxing
│   │   └── main.py       # FastAPI app entrypoint
│   └── tests/
├── gateway/              # TypeScript WebSocket gateway
│   └── src/
├── frontend/             # Next.js web UI
│   └── src/
├── spacetimedb/          # SpacetimeDB module (TypeScript)
│   └── spacetimedb/
├── migrations/           # SQLite schema migrations
├── prompts/              # System prompt fragments
├── scripts/              # Setup & maintenance scripts
├── docs/                 # Architecture docs & guides
├── docker/               # Dockerfiles for agent containers
├── bond.json             # Primary configuration
├── Makefile              # All commands live here
└── pyproject.toml        # Python project config

make backend    # Just the FastAPI server
make gateway    # Just the WebSocket gateway
make frontend   # Just the Next.js UI

make test       # All tests
uv run pytest   # Python tests only
cd gateway && pnpm test    # Gateway tests only
cd frontend && pnpm test   # Frontend tests only

# Create migration files
~/go/bin/migrate create -ext sql -dir migrations -seq <name>

# Edit the .up.sql and .down.sql files, then:
make migrate

Private — see repository for details.