ZeroDB Local

Run ZeroDB on your local machine. Two modes available:

Lite mode (recommended) — pip install, no Docker required
Full mode — Docker Compose with PostgreSQL, Qdrant, MinIO, RedPanda

Quick Start — Lite Mode (No Docker)

pip install zerodb-local[lite]
zerodb serve

That's it. Server starts at http://localhost:8000 with:

SQLite database
FAISS vector search
In-process embeddings (BAAI/bge-small-en-v1.5, 384 dims)
Local filesystem storage
SQLite event queue

Verify it works

# Health check
curl http://localhost:8000/health

# Create a project
curl -X POST http://localhost:8000/v1/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "description": "Testing ZeroDB Local"}'

CLI Options

zerodb serve                        # Start on port 8000
zerodb serve --port 9000            # Custom port
zerodb serve --data-dir /my/data    # Custom data directory
zerodb serve --cloud-key sk_...     # Enable cloud sync

Data is stored at ~/.zerodb/data/ by default.

Features

Two backends: Lite (SQLite + FAISS) or Full (PostgreSQL + Qdrant + Docker)
Local API Server: Mirrors all 128 ZeroDB Cloud endpoints
Web Dashboard: Manage projects, vectors, tables, files, and events via UI
CLI Tool: zerodb command for local control and cloud sync
Offline-First: Work without internet, sync when ready
No API Costs: Local embeddings using BAAI BGE models (free)
Cloud Sync: Bidirectional sync with ZeroDB Cloud
Production-Ready: Same code paths as cloud for consistency

Full Mode (Docker)

For production-like environments with PostgreSQL, Qdrant, MinIO, and RedPanda.

Prerequisites

Docker 20.10+ and Docker Compose 2.0+
Python 3.11+ (for CLI tool)
At least 4GB RAM available for Docker

Installation

Clone the repository:
```
cd zerodb-local
```
Copy environment template:
```
cp .env.local.example .env.local
```
Edit .env.local (optional):
- Update POSTGRES_PASSWORD for production use
- Set CLOUD_API_KEY if you want cloud sync
- Adjust EMBEDDINGS_MODEL based on your needs
Start all services:
```
docker-compose up -d
```
Verify services are running:
```
docker-compose ps
```
You should see 7 services running:
- zerodb-postgres (PostgreSQL + pgvector)
- zerodb-qdrant (Vector search)
- zerodb-minio (Object storage)
- zerodb-redpanda (Event streaming)
- zerodb-embeddings (Local embeddings)
- zerodb-api (API server)
- zerodb-dashboard (Web UI)
Access the dashboard:
- Open http://localhost:3000 in your browser
Check API health:
```
curl http://localhost:8000/health
```

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ZeroDB Local Stack                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐         ┌──────────────┐                   │
│  │  Dashboard  │◄────────┤   API Server │                   │
│  │ (React UI)  │  REST   │   (FastAPI)  │                   │
│  └─────────────┘         └───────┬──────┘                   │
│   localhost:3000                 │                           │
│                                  │                           │
│          ┌───────────────────────┼───────────────────┐       │
│          │                       │                   │       │
│          ▼                       ▼                   ▼       │
│  ┌──────────────┐      ┌─────────────┐     ┌─────────────┐  │
│  │  PostgreSQL  │      │   Qdrant    │     │    MinIO    │  │
│  │  + pgvector  │      │  (Vectors)  │     │   (Files)   │  │
│  └──────────────┘      └─────────────┘     └─────────────┘  │
│   localhost:5432        localhost:6333      localhost:9000  │
│                                                              │
│          ┌───────────────────────┬──────────────────┐        │
│          │                       │                  │        │
│          ▼                       ▼                  ▼        │
│  ┌──────────────┐      ┌─────────────┐     ┌─────────────┐  │
│  │   RedPanda   │      │ Embeddings  │     │    CLI      │  │
│  │   (Events)   │      │   (BAAI)    │     │   (Typer)   │  │
│  └──────────────┘      └─────────────┘     └─────────────┘  │
│   localhost:9092        localhost:8001      zerodb command  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ Sync (optional)
                            ▼
                  ┌─────────────────────┐
                  │  ZeroDB Cloud API   │
                  │ api.ainative.studio │
                  └─────────────────────┘

Services

PostgreSQL + pgvector (Port 5432)

Purpose: Relational data storage with vector support
Storage: ./data/postgres
Console: Access via psql or any PostgreSQL client
Usage: Tables, metadata, change logs

Qdrant (Port 6333)

Purpose: High-performance vector similarity search
Storage: ./data/qdrant
Web UI: http://localhost:6333/dashboard
Usage: Fast semantic search for vectors and memory

MinIO (Port 9000/9001)

Purpose: S3-compatible object storage
Storage: ./data/minio
Console: http://localhost:9001 (minioadmin/minioadmin)
Usage: File uploads, large blobs

RedPanda (Port 9092)

Purpose: Kafka-compatible event streaming
Storage: ./data/redpanda
Console: http://localhost:9644
Usage: Event sourcing, CDC, real-time notifications

Embeddings Service (Port 8001)

Purpose: Local text embedding generation
Model: BAAI/bge-small-en-v1.5 (384 dimensions)
Storage: ./data/embeddings/models
Usage: Generate embeddings without API costs

API Server (Port 8000)

Purpose: FastAPI server mirroring ZeroDB Cloud
Endpoints: 128 endpoints matching cloud API
Docs: http://localhost:8000/docs
Health: http://localhost:8000/health

Dashboard (Port 3000)

Purpose: Web UI for local management
Framework: React 18 + TypeScript + Vite
Features: Projects, vectors, tables, files, events, sync

Usage Examples

Create a Project

curl -X POST http://localhost:8000/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-project",
    "description": "Testing ZeroDB Local"
  }'

Upsert a Vector

curl -X POST http://localhost:8000/v1/projects/{project_id}/database/vectors/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "vector_embedding": [0.1, 0.2, 0.3, ...],
    "document": "This is my document",
    "metadata": {"source": "local-test"}
  }'

Search Vectors

curl -X POST http://localhost:8000/v1/projects/{project_id}/database/vectors/search \
  -H "Content-Type: application/json" \
  -d '{
    "query_vector": [0.1, 0.2, 0.3, ...],
    "limit": 10,
    "threshold": 0.7
  }'

CLI Tool

Installation

cd cli
pip install -e .

Commands

# Start local environment
zerodb local up

# Stop local environment
zerodb local down

# Check service status
zerodb local status

# Login to cloud
zerodb cloud login

# Link local project to cloud
zerodb cloud link <project_id>

# Sync to cloud (push)
zerodb sync apply

# Pull from cloud
zerodb cloud pull

Data Management

Backup Local Data

./scripts/backup-local.sh

Creates backup in ./backups/zerodb-backup-YYYY-MM-DD.tar.gz

Restore from Backup

./scripts/restore-local.sh ./backups/zerodb-backup-YYYY-MM-DD.tar.gz

Reset Everything

docker-compose down -v
rm -rf ./data
docker-compose up -d

Development

Hot Reload API

cd api
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Hot Reload Dashboard

cd dashboard
npm run dev

Run Tests

cd api
pytest tests/ -v --cov

Troubleshooting

Services won't start

# Check logs
docker-compose logs

# Restart specific service
docker-compose restart zerodb-api

# Full reset
docker-compose down -v && docker-compose up -d

Port conflicts

# Check what's using the ports
lsof -i :5432   # PostgreSQL
lsof -i :6333   # Qdrant
lsof -i :9000   # MinIO
lsof -i :9092   # RedPanda
lsof -i :8000   # API
lsof -i :3000   # Dashboard

# Update ports in docker-compose.yml if needed

Slow embeddings

# Use GPU if available (NVIDIA)
# Update .env.local:
EMBEDDINGS_DEVICE=cuda

# Or use larger model (slower but more accurate)
EMBEDDINGS_MODEL=BAAI/bge-base-en-v1.5  # 768 dims
EMBEDDINGS_MODEL=BAAI/bge-large-en-v1.5  # 1024 dims

Database connection issues

# Check Postgres is healthy
docker-compose exec postgres pg_isready

# Inspect logs
docker-compose logs postgres

# Connect manually
docker-compose exec postgres psql -U zerodb -d zerodb_local

Cloud Sync

Setup

Get your API key from https://www.ainative.studio/dashboard/api-keys
Add to .env.local:
```
CLOUD_API_KEY=your-api-key-here
```
Login via CLI:
```
zerodb cloud login
```

Sync Workflow

# 1. Make changes locally (add vectors, tables, etc.)

# 2. See what will be synced
zerodb sync plan

# 3. Push to cloud
zerodb sync apply

# 4. Pull changes from cloud
zerodb cloud pull

Conflict Resolution

Configure in .env.local:

CONFLICT_RESOLUTION=newest-wins  # local-wins, cloud-wins, newest-wins, manual

Environment Variables Reference

See .env.local.example for complete list. Key variables:

POSTGRES_PASSWORD - Database password (change in production!)
CLOUD_API_KEY - Your ZeroDB Cloud API key for sync
EMBEDDINGS_MODEL - Model to use (small/base/large)
LOG_LEVEL - Logging verbosity (debug/info/warning/error)
DEBUG - Enable debug mode (true/false)

System Requirements

Minimum

4GB RAM
10GB disk space
2 CPU cores
Docker 20.10+

Performance

Expected Latency

Vector upsert: <10ms
Semantic search (10k vectors): <50ms
Embeddings generation: <100ms per text
Sync (1k vectors): <30s

Scaling Limits (Local)

Vectors: Up to 1M (limited by RAM)
Tables: Unlimited (limited by disk)
Files: Unlimited (limited by disk)
Events: 10k/sec (limited by RedPanda)

Security

Default Credentials

⚠️ CHANGE THESE IN PRODUCTION!

PostgreSQL: zerodb / localpass
MinIO: minioadmin / minioadmin
API JWT Secret: (generated automatically)

Best Practices

Use strong passwords in .env.local
Never commit .env.local to git
Use API keys for cloud sync (not passwords)
Enable HTTPS for remote access
Restrict CORS origins in production

Documentation

Quick Start: docs/QUICK_START.md - Step-by-step setup guide
Environment Setup: docs/ENVIRONMENT_SETUP.md - Configuration for local/staging/production
Data Management: docs/DATA_MANAGEMENT.md - Backups, restores, and data lifecycle
Troubleshooting: docs/TROUBLESHOOTING.md - Common issues and solutions
Sync Strategy: docs/SYNC_STRATEGY.md - Cloud sync configuration
API Reference: http://localhost:8000/docs - Interactive API documentation

Port Configuration

All external port mappings in docker-compose.yml are configurable via environment variables. Each defaults to the standard port if unset.

Service	Default Port	Environment Variable
PostgreSQL	5432	`ZERODB_POSTGRES_PORT`
Qdrant REST	6333	`ZERODB_QDRANT_REST_PORT`
Qdrant gRPC	6334	`ZERODB_QDRANT_GRPC_PORT`
MinIO API	9000	`ZERODB_MINIO_API_PORT`
MinIO Console	9001	`ZERODB_MINIO_CONSOLE_PORT`
RedPanda Kafka	9092	`ZERODB_REDPANDA_KAFKA_PORT`
RedPanda HTTP Proxy	8082	`ZERODB_REDPANDA_PROXY_PORT`
RedPanda Admin	9644	`ZERODB_REDPANDA_ADMIN_PORT`
Embeddings	8001	`ZERODB_EMBEDDINGS_PORT`
API Server	8000	`ZERODB_API_PORT`
Dashboard	3000	`ZERODB_DASHBOARD_PORT`

Remapping Ports

Set variables in your .env.local file or pass them directly:

# Via .env.local
ZERODB_API_PORT=8080
ZERODB_DASHBOARD_PORT=3001
ZERODB_POSTGRES_PORT=5433

# Or inline
ZERODB_API_PORT=8080 docker-compose up -d

Using docker-compose.override.yml

For persistent local overrides without modifying tracked files, create a docker-compose.override.yml:

version: '3.8'
services:
  zerodb-api:
    ports:
      - "8080:8000"
  dashboard:
    ports:
      - "3001:3000"
  postgres:
    ports:
      - "5433:5432"

Docker Compose automatically merges this file with docker-compose.yml on every docker-compose up.

Port Conflict Detection

The port-config.json file in this directory describes all service ports and their env vars. It can be consumed by the port-management skill or any automation tool to detect conflicts before starting the stack.

Support

GitHub Issues: https://github.com/AINative-Studio/core/issues
Documentation: https://www.ainative.studio/docs
Community: https://www.ainative.studio/community
Email: hello@ainative.studio

License

MIT License. See LICENSE for details.

Built with ❤️ by the AINative Studio team

Name		Name	Last commit message	Last commit date
.github		.github
api		api
benchmarks		benchmarks
cli		cli
dashboard		dashboard
desktop		desktop
docs		docs
embeddings		embeddings
lite		lite
packages/zerolocal-macos		packages/zerolocal-macos
scripts		scripts
tests		tests
zerodb_local		zerodb_local
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
docker-compose.yml		docker-compose.yml
port-config.json		port-config.json
pyproject.toml		pyproject.toml
test_cli_login.sh		test_cli_login.sh

Latest commit

History

Folders and files

Repository files navigation

ZeroDB Local

Quick Start — Lite Mode (No Docker)

Verify it works

CLI Options

Features

Full Mode (Docker)

Prerequisites

Installation

Architecture

Services

PostgreSQL + pgvector (Port 5432)

Qdrant (Port 6333)

MinIO (Port 9000/9001)

RedPanda (Port 9092)

Embeddings Service (Port 8001)

API Server (Port 8000)

Dashboard (Port 3000)

Usage Examples

Create a Project

Upsert a Vector

Search Vectors

CLI Tool

Installation

Commands

Data Management

Backup Local Data

Restore from Backup

Reset Everything

Development

Hot Reload API

Hot Reload Dashboard

Run Tests

Troubleshooting

Services won't start

Port conflicts

Slow embeddings

Database connection issues

Cloud Sync

Setup

Sync Workflow

Conflict Resolution

Environment Variables Reference

System Requirements

Minimum

Recommended

Performance

Expected Latency

Scaling Limits (Local)

Security

Default Credentials

Best Practices

Documentation

Port Configuration

Remapping Ports

Using docker-compose.override.yml

Port Conflict Detection

Support

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages