Bonds

📖 Documentation | 中文文档 | 💬 Discord

A modern, community-driven personal relationship manager, inspired by Monica, rebuilt with Go and React.

Why Bonds?

Monica is a beloved open-source personal CRM with 24k+ stars. But as a side project maintained by a tiny team (their own words), development has slowed, leaving 700+ open issues and limited bandwidth.

Bonds picks up where Monica left off:

• Fast and lightweight: Single binary, starts in milliseconds, minimal memory.
• Easy to deploy: One binary + SQLite. No PHP, no Composer, no Node runtime.
• Modern UI: React 19 + TypeScript, smooth SPA experience.
• Well tested: 1014 backend tests, 129 frontend tests, 180 E2E tests.
• Community first: Built for contributions and fast iteration.

Credits: Bonds stands on the shoulders of @djaiss, @asbiin, and the entire Monica community. The original Monica remains available under AGPL-3.0 at monicahq/monica.

Features

• Contacts: Full lifecycle management with notes, tasks, reminders, gifts, debts, activities, life events, pets, and more. Includes a needs-verification flag to keep your data fresh.
• Vault Dashboard: Responsive 3-column layout with activity feed, life events, life metrics tracking (+1 counter), mood recording, upcoming reminders, and due tasks.
• Vaults: Multi-vault data isolation with role-based access (Manager, Editor, Viewer).
• Reminders: One-time and recurring (weekly, monthly, yearly), with email and Shoutrrr-compatible notifications.
• Full-text Search: Bleve-powered CJK-aware search across contacts and notes.
• CardDAV / CalDAV: Sync contacts and calendars with Apple, Thunderbird, and other DAV clients. Supports Personal Access Tokens.
• DAV Sync Subscriptions: Subscribe to and sync from external CardDAV address books directly into a vault.
• Personal Access Tokens: Generate secure API and sync tokens to access endpoints safely.
• AI Agent Access (MCP): Built-in /mcp endpoint for MCP clients. Agents can discover capabilities, search vault data, fetch resources, and execute existing /api operations with the same auth and permissions. See AI Agent Access.
• CSV Import: Import contacts from a CSV file with a user-defined column mapping (name, email, phone, birthday, address, tags, groups, notes).
• Monica Import: Migrate contacts directly from a Monica instance via API.
• vCard Import/Export: Bulk import .vcf files, export individual or all contacts.
• File Upload: Photos and documents attached to contacts, with generated initials avatars. Storage size limits managed directly from the UI.
• Two-Factor Auth (TOTP): TOTP-based 2FA with recovery codes.
• WebAuthn / FIDO2: Passkey login (hardware keys, biometrics).
• OAuth Login: GitHub and Google single sign-on.
• User Invitations: Invite others to your account via email with permission levels.
• Audit Log: Feed of all changes across contacts.
• Geocoding: Address coordinates via Nominatim (free) or LocationIQ.
• Shoutrrr Notifications: Reminder delivery via Telegram and other Shoutrrr-compatible channels.
• i18n: English and Chinese, frontend and backend.

Quick Start

Option 1: Docker (Recommended)

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/naiba/bonds/main/docker-compose.yml

# Start the service
docker compose up -d

Open http://localhost:8080 and create your account.

To customize settings, edit docker-compose.yml:

environment:
  - JWT_SECRET=your-secret-key-here   # ⚠️ Change this!

Option 2: Pre-built Binary

Download the latest release from GitHub Releases, then:

export JWT_SECRET=your-secret-key-here
./bonds-server

The server starts at http://localhost:8080 with an embedded frontend and SQLite database.

Option 3: Build from Source

Prerequisites: Go 1.25+, Bun 1.x

git clone https://github.com/naiba/bonds.git
cd bonds

# Install dependencies
make setup

# Build a single binary (frontend embedded)
make build-all

# Run it
export JWT_SECRET=your-secret-key-here
./server/bin/bonds-server

Configuration

Bonds uses a hybrid configuration approach:

• Environment variables: For essential infrastructure settings (database, server, security).
• Admin UI: For all runtime settings (SMTP, OAuth, Telegram, WebAuthn, storage size limit, etc.).

On first startup, environment variables are seeded into the database. After that, manage settings from Admin > System Settings in the web UI.

cp server/.env.example server/.env

Environment Variables (Required)

Variable	Default	Description
DEBUG	false	Enable debug mode: Echo request logging, GORM SQL logging, Swagger UI (default on)
JWT_SECRET	—	Required in production. Signing key for auth tokens
SETTINGS_ENC_KEY	(empty)	Optional. Enables AES-256-GCM encryption-at-rest for SMTP/OAuth/geocoding secrets. See docs
SERVER_PORT	8080	Port the server listens on
SERVER_HOST	0.0.0.0	Host address the server binds to
DB_DSN	bonds.db	Database connection string. SQLite: file path; PostgreSQL: host=... port=5432 user=... password=... dbname=... sslmode=disable
DB_DRIVER	sqlite	Database driver (sqlite or postgres)
APP_ENV	development	Set to production for production use
STORAGE_UPLOAD_DIR	uploads	File upload directory
BLEVE_INDEX_PATH	data/bonds.bleve	Full-text search index directory
BACKUP_DIR	data/backups	Directory to store backup files

Admin UI Settings

The following are managed from the Admin > System Settings page after login:

• Application: Name, URL, Announcement banner.
• Authentication: Password auth toggle, User registration toggle.
• JWT: Token expiry, Refresh window.
• SMTP: Host, Port, Username, Password, Sender email.
• OAuth / OIDC: GitHub, Google, and OIDC/SSO credentials.
• WebAuthn: Relying Party ID, Display Name, Origins.
• Telegram: Bot token for notifications.
• Geocoding: Provider (Nominatim/LocationIQ), API key.
• Storage: Max upload size limit.
• Backup: Cron schedule, Retention days.
• Swagger: Enable or disable API documentation UI.

Development

# Install dependencies
make setup

# Generate API client (required before first build)
make gen-api

# Start both frontend and backend in dev mode
make dev

This runs the Go backend on :8080 and the Vite dev server on :5173. The frontend automatically proxies API requests to the backend.

Code Generation Pipeline

The frontend TypeScript API client is auto-generated from the backend OpenAPI schema. The generated files are not committed to git. They are regenerated in CI and during development.

Go handlers (swag annotations)
    ↓  make swagger
server/docs/swagger.json
    ↓  make gen-api (or bun run gen:api)
web/src/api/generated/   ← gitignored, regenerated on demand
    ↓
web/src/api/index.ts     ← entry point, imports generated modules

After changing any backend API (handlers, DTOs, routes), run:

make gen-api       # Regenerate swagger.json + TypeScript API client

Useful Commands

make dev           # Start frontend + backend in dev mode
make build         # Build backend + frontend separately
make build-all     # Build single binary with embedded frontend
make test          # Run all tests (backend + frontend)
make test-e2e      # Run end-to-end tests (Playwright)
make lint          # Run linters (go vet + eslint)
make swagger       # Regenerate Swagger/OpenAPI docs only
make gen-api       # Regenerate Swagger docs + TypeScript API client
make clean         # Clean all build artifacts + generated files
make setup         # Install all dependencies

API Documentation

Bonds provides auto-generated OpenAPI/Swagger documentation covering all API endpoints.

To access the Swagger UI, either enable debug mode or toggle it on in Admin > Settings > Swagger:

# Option 1: Debug mode (Swagger enabled by default)
DEBUG=true ./bonds-server
# Option 2: Enable via Admin UI without debug mode
# Go to Admin > Settings > Swagger > Enable

Then open http://localhost:8080/swagger/index.html

Swagger UI defaults to the DEBUG flag, but can be independently toggled from the Admin Settings page.

Relationship to Monica

Bonds is a ground-up rewrite inspired by Monica (AGPL-3.0). It re-implements Monica's data model and feature set using a completely different tech stack (Go + React instead of PHP/Laravel + Vue). It contains no code from the original project.

License

Business Source License 1.1 (BSL 1.1), Source Available license with the following terms:

• Individuals: Free for any non-commercial use.
• Organizations: Commercial use requires a paid license from the Licensor.
• Prohibited: Reselling, sublicensing, or offering as a managed/hosted service.
• Change Date: June 13, 2030, automatically converts to AGPL-3.0 (same as original Monica).

After the Change Date, the software becomes fully open source under AGPL-3.0.

By submitting code, documentation, translations, or any other contribution, you agree to the contribution terms, including waiving all ownership and other rights or claims in that contribution to the fullest extent permitted by law.