cyborginc/cyborgdb-service repository overview

⁠

⁠CyborgDB Service

CyborgDB Service is the FastAPI-based REST API server for CyborgDB⁠ — the vector database that stays encrypted even while it's searching. It serves encrypted vector ingestion, search, and retrieval over HTTP: vectors stay encrypted through search, and only the result of a query is decrypted. This image is CPU-optimized and multi-arch — run it in your own VPC or on-prem.

⁠Features

• Encryption-in-use: Vectors stay encrypted at rest, in transit, and through search — only the query result is decrypted
• Encrypted ANN: Disk-backed encrypted DiskIVF index with recall within 2% of a plaintext baseline (read the benchmarks⁠)
• Filters on encrypted metadata: Combine vector similarity with equality and range predicates in a single request
• BYOK / HYOK: Per-index key wrapping via AWS KMS or AWS Secrets Manager, including cross-account BYOK (KMS and BYOK guide⁠)
• Per-tenant key isolation: Per-index, per-user keys with cryptographic RBAC; revoke a user and their keys are erased
• Multiple backing stores: Embedded disk storage or AWS S3 / S3-compatible object storage

⁠Quick Start

Evaluating? Use docker run below. Deploying? Jump to Docker Compose⁠.

No API key is required: without one the service runs the free tier (per-index cap: 1,000,000 items). Add -e CYBORGDB_API_KEY=cyborg_... for unlimited usage — create a key at cyborgdb.co/new⁠.

Data lives in /app/cyborgdb_data inside the container; the -v mount below keeps it across restarts.

docker run --rm -p 127.0.0.1:8000:8000 \
  -v cyborgdb_data:/app/cyborgdb_data \
  cyborginc/cyborgdb-service:latest

Check that it is up:

curl http://localhost:8000/v1/health

Interactive API docs: http://localhost:8000/v1/docs⁠.

The command above exposes the service only on the Docker host's localhost interface. For remote deployments, set CYBORGDB_SERVICE_ROOT_KEY and configure clients to send that key or a cdbk_ user token. CYBORGDB_API_KEY controls licensing; it does not authenticate REST requests. Do not expose an unauthenticated service to remote clients.

⁠First query

With the service running, install the Python client and complete a connect → index → upsert → query loop:

pip install cyborgdb

import cyborgdb
import secrets

# Connect to the running service.
client = cyborgdb.Client(base_url="http://localhost:8000")

# Generate an encryption key for the index.
# WARNING: store this key securely — data encrypted with a lost key is unrecoverable.
index_key = secrets.token_bytes(32)

# Create an encrypted index.
index = client.create_index(index_name="my_index", index_key=index_key)

# Upsert some items.
items = [
    {"id": "item_1", "vector": [0.1, 0.2, 0.3, 0.4], "contents": "Hello!"},
    {"id": "item_2", "vector": [0.5, 0.6, 0.7, 0.8], "contents": "Bonjour!"},
    {"id": "item_3", "vector": [0.9, 0.10, 0.11, 0.12], "contents": "Hola!"},
]
index.upsert(items)

# Query — include distance + metadata, then chain get() for contents.
results = index.query(
    query_vectors=[0.1, 0.2, 0.3, 0.4],
    top_k=2,
    include=["distance", "metadata"],
)
top_items = index.get([r["id"] for r in results])
by_id = {item["id"]: item for item in top_items}
for r in results:
    contents = by_id[r["id"]]["contents"]
    print(f"ID: {r['id']}  Distance: {r['distance']:.4f}  Contents: {contents}")

JavaScript/TypeScript and Go clients: see the SDK docs⁠.

⁠Deployment Scenarios

⁠1. Local disk (no credentials needed)

Disk is the default (see Quick Start above).

⁠2. S3 on AWS (ECS / EC2 / EKS — no explicit credentials)

On AWS infrastructure, do not pass credentials: the AWS default credential provider chain picks up the task/instance role automatically.

docker run -it -p 127.0.0.1:8000:8000 \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=my-bucket \
  -e CYBORGDB_S3_REGION=us-east-1 \
  cyborginc/cyborgdb-service:latest

⁠3. S3 from outside AWS (AWS_* env vars or mounted profile)

Off AWS, hand the default chain credentials the usual way — AWS_* environment variables or a mounted ~/.aws profile:

docker run -it -p 127.0.0.1:8000:8000 \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=my-bucket \
  -e CYBORGDB_S3_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN \
  cyborginc/cyborgdb-service:latest

⁠4. S3-compatible storage (MinIO etc.) + AWS KMS

A custom endpoint means "this is not AWS": explicit CYBORGDB_S3_* credentials are required, and the AWS chain is never used against the endpoint (startup fails fast if the keys are missing). The CYBORGDB_S3_* namespace is deliberately separate from AWS_*, so the same container can talk to MinIO for storage and AWS for KMS/BYOK without the credentials colliding:

docker run -it -p 127.0.0.1:8000:8000 \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=cyborgdb \
  -e CYBORGDB_S3_ENDPOINT=https://minio.internal:9000 \
  -e CYBORGDB_S3_ACCESS_KEY=minio-access-key \
  -e CYBORGDB_S3_SECRET_KEY=minio-secret-key \
  -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION \
  cyborginc/cyborgdb-service:latest

⁠Multi-Architecture Support

This image supports multiple architectures and will automatically pull the correct one for your system:

⁠Docker Compose

⁠Disk (default)

services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "127.0.0.1:8000:8000"
    # CYBORGDB_API_KEY is optional (free tier when unset); add it for
    # unlimited usage.
    # environment:
    #   - CYBORGDB_API_KEY=cyborg_your_api_key_here
    volumes:
      - cyborgdb_data:/app/cyborgdb_data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/v1/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  cyborgdb_data:

⁠S3

services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      - CYBORGDB_API_KEY=cyborg_your_api_key_here
      - CYBORGDB_DB_TYPE=s3
      - CYBORGDB_S3_BUCKET=my-bucket
      - CYBORGDB_S3_REGION=us-east-1
      # Off AWS: forward chain credentials (omit on ECS/EC2/EKS).
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_SESSION_TOKEN
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/v1/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Run either file with docker compose up -d.

A YAML config file (service settings + per-index KMS registry) can be mounted to /app/cyborgdb.yaml — see the YAML reference⁠.

⁠Environment Variables

⁠Storage Backends

⁠Disk (default)

• Data directory: CYBORGDB_DISK_PATH (the image defaults it to /app/cyborgdb_data — mount a volume there)
• Recommended for: Single-instance deployments, edge deployments, maximum performance
• Performance: Fastest option — embedded storage with no network overhead

⁠S3 / S3-compatible

• Required: CYBORGDB_S3_BUCKET
• Credentials: AWS default credential chain by default; explicit CYBORGDB_S3_* keys required with a custom endpoint (see Deployment Scenarios above)
• Recommended for: Cloud-native deployments, large-scale storage
• Performance: Network-bound

⁠Image Details

• Base Image: python:3.14-slim
• Python Version: 3.14
• Image size: about 124 MB compressed per architecture; no PyTorch bundled
• Text embedding: built into cyborgdb-core; models download on first use
• Platforms: linux/amd64, linux/arm64

⁠Links

• Documentation⁠ · Changelog⁠ · Get an API key⁠ · Contact⁠
• Client SDKs: Python⁠ · JavaScript/TypeScript⁠ · Go⁠