Docker Service Quickstart

CyborgDB can be deployed as a standalone microservice using Docker. This allows you to run a fully self-contained encrypted vector search service on your own infrastructure with minimal setup. The service exposes a REST API for integration with any stack.

Looking to use the Python service? Check out our Python Quickstart Guide.

Overview

The Docker service is ideal for teams looking to self-host CyborgDB in cloud, on-prem, or containerized environments.

Get an API Key (Optional)

The service runs without an API key — leave CYBORGDB_API_KEY unset and the core engine starts in free-tier mode, capped at 1,000,000 items per index. Set it to lift that cap. Get a key from the CyborgDB Admin Dashboard, or generate a temporary demo key with any of the SDKs:

import cyborgdb
print(cyborgdb.get_demo_api_key())

import { getDemoApiKey } from 'cyborgdb';
console.log(await getDemoApiKey());

demoKey, _ := cyborgdb.GetDemoAPIKey("my demo app")
fmt.Println(demoKey)

Pass the key as CYBORGDB_API_KEY when starting the service. This is the core license key, not a service-authentication credential — it does not gate access to the REST API.

Service authentication is separate and controlled by CYBORGDB_SERVICE_ROOT_KEY. Leave it unset (the default) and the service accepts all requests. Set it to require callers to send the root key — or a cdbk_ user token minted under it — in the X-API-Key header. See Managing Keys.

Choose Your Storage Backend (Optional)

The container ships with three storage backends. Skip this step and you get disk by default — persisted in /app/cyborgdb_data inside the container, which you’ll typically bind to a host volume.

Disk (default) — persistent local disk, no external dependencies.
S3 — AWS S3 or any S3-compatible store (MinIO, Cloudflare R2, …). Best for cloud-native and multi-replica deployments.
Memory — in-process only, nothing persists across restarts. For tests and ephemeral indexes.

For full details, see the Backing Stores guide.

Pull the Docker Image

The CyborgDB service is available as a Docker image. You can pull it from Docker Hub:

docker pull cyborginc/cyborgdb-service:latest

This image contains everything you need to run the CyborgDB service, including all dependencies and configurations.

Run with Docker (Quick Start)

Disk (default)
Memory
S3 (AWS)
S3 (MinIO / R2)

# Minimal — no API key needed; disk is the default; bind the data dir to a host volume
sudo docker run -it --rm --network host \
  -v cyborgdb_data:/app/cyborgdb_data \
  cyborginc/cyborgdb-service:latest

sudo docker run -it -p 8000:8000 \
  -v cyborgdb_data:/app/cyborgdb_data \
  cyborginc/cyborgdb-service:latest

Inside the container the disk path defaults to /app/cyborgdb_data — the -v mount above is what makes the data survive container recreation. Add -e CYBORGDB_API_KEY=… to lift the free-tier 1M-items-per-index cap.

sudo docker run -it --rm --network host \
  -e CYBORGDB_DB_TYPE=memory \
  cyborginc/cyborgdb-service:latest

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=memory \
  cyborginc/cyborgdb-service:latest

Memory storage does not persist across container restarts. Use for tests and ephemeral indexes only.

sudo docker run -it --network host \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=my-bucket \
  -e CYBORGDB_S3_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=AKID... \
  -e AWS_SECRET_ACCESS_KEY=... \
  cyborginc/cyborgdb-service:latest

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=my-bucket \
  -e CYBORGDB_S3_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=AKID... \
  -e AWS_SECRET_ACCESS_KEY=... \
  cyborginc/cyborgdb-service:latest

On EC2/ECS/EKS the instance/task role is picked up automatically — drop the AWS_* vars.

sudo docker run -it --network host \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=my-bucket \
  -e CYBORGDB_S3_ENDPOINT=http://minio:9000 \
  -e CYBORGDB_S3_ACCESS_KEY=minioadmin \
  -e CYBORGDB_S3_SECRET_KEY=minioadmin \
  cyborginc/cyborgdb-service:latest

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=my-bucket \
  -e CYBORGDB_S3_ENDPOINT=http://host.docker.internal:9000 \
  -e CYBORGDB_S3_ACCESS_KEY=minioadmin \
  -e CYBORGDB_S3_SECRET_KEY=minioadmin \
  cyborginc/cyborgdb-service:latest

With a custom CYBORGDB_S3_ENDPOINT the AWS default credential chain is bypassed entirely — CYBORGDB_S3_ACCESS_KEY / CYBORGDB_S3_SECRET_KEY are required.

Platform Differences:

Linux uses --network host because Docker runs natively and can directly access the host network
macOS uses -p 8000:8000 and host.docker.internal because Docker runs in a VM and needs port mapping

Run with Docker Compose (Recommended)

For a reproducible setup, use Docker Compose:

Disk (default)
S3 (AWS)
S3 (MinIO)

Create a docker-compose.yml file:

services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    # No API key needed; add CYBORGDB_API_KEY to lift the free-tier cap:
    # environment:
    #   - CYBORGDB_API_KEY=${CYBORGDB_API_KEY}
    volumes:
      - cyborgdb_data:/app/cyborgdb_data
      - ./logs:/app/logs

volumes:
  cyborgdb_data:

Then run:

docker-compose up -d

Create a docker-compose.yml file:

services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_API_KEY=${CYBORGDB_API_KEY}
      - CYBORGDB_DB_TYPE=s3
      - CYBORGDB_S3_BUCKET=${CYBORGDB_S3_BUCKET}
      - CYBORGDB_S3_REGION=${CYBORGDB_S3_REGION:-us-east-1}
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}

Then run:

docker-compose up -d

Bring up MinIO + cyborgdb-service together:

services:
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data

  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_API_KEY=${CYBORGDB_API_KEY}
      - CYBORGDB_DB_TYPE=s3
      - CYBORGDB_S3_BUCKET=cyborgdb
      - CYBORGDB_S3_ENDPOINT=http://minio:9000
      - CYBORGDB_S3_ACCESS_KEY=minioadmin
      - CYBORGDB_S3_SECRET_KEY=minioadmin
    depends_on:
      - minio

volumes:
  minio_data:

Then run:

docker-compose up -d

Create the cyborgdb bucket once via the MinIO console (http://localhost:9001) before first use.

Verify Installation

Once the service is running, verify it’s working correctly:Health Check:

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

API Documentation: Navigate to http://localhost:8000/v1/docs to explore the interactive API documentation.You should see a response indicating the service is healthy and ready to accept requests.

Run Your First Query

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

pip install cyborgdb

Python

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 (index_key is required on every data operation).
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, index_key=index_key)

# 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"],
    index_key=index_key,
)
top_items = index.get([r["id"] for r in results], index_key=index_key)
by_id = {item["id"]: item for item in top_items}
for r in results:
    contents = by_id[r["id"]]["contents"].decode()
    print(f"ID: {r['id']}  Distance: {r['distance']:.4f}  Contents: {contents}")

Store index_key before you upsert any data. CyborgDB has no key-recovery path — data encrypted with a lost key is unrecoverable. For anything past evaluation, keep the key in AWS Secrets Manager, Vault, or your KMS. See Managing Keys.

index_key is a 32-byte per-index encryption key you generate and hold. It’s separate from CYBORGDB_API_KEY (the core license key) and CYBORGDB_SERVICE_ROOT_KEY (service authentication).

Advanced Configuration

For production deployments, consider these additional configurations:

Environment Variables
HTTPS Configuration

Variable	Description	Required	Example
`CYBORGDB_API_KEY`	Core license key. Free tier (1M items/index) when unset	❌	`cyborg_abc123...`
`CYBORGDB_SERVICE_ROOT_KEY`	Service auth root (an operator-chosen secret). Auth disabled (all requests allowed) when unset	❌	`a-long-random-secret`
`CYBORGDB_DB_TYPE`	Storage backend (`memory`, `disk`, `s3`)	❌ (defaults to `disk`)	`s3`
`CYBORGDB_DISK_PATH`	Data directory for `disk` storage	❌	`/var/lib/cyborgdb`
`CYBORGDB_S3_BUCKET`	Bucket name for `s3` storage	Required for S3	`my-bucket`
`CYBORGDB_S3_REGION`	Region for `s3` storage	❌	`us-east-1`
`PORT`	Service port	❌	`8000`
`SSL_CERT_PATH`	Path to SSL certificate file	❌	`/etc/ssl/certs/server.crt`
`SSL_KEY_PATH`	Path to SSL private key file	❌	`/etc/ssl/private/server.key`

None of these are required — the container starts with no configuration, using disk storage rooted at /app/cyborgdb_data, free-tier licensing, and authentication disabled. For the full list (including S3 credentials and KMS), see the Environment Variables guide.

For production deployments, configure HTTPS by providing SSL certificates:Environment Variables:

SSL_CERT_PATH=/path/to/certificate.crt
SSL_KEY_PATH=/path/to/private.key

Docker Run Example:

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e CYBORGDB_DB_TYPE=s3 \
  -e CYBORGDB_S3_BUCKET=cyborgdb-prod \
  -e CYBORGDB_S3_REGION=us-east-1 \
  -e SSL_CERT_PATH=/certs/server.crt \
  -e SSL_KEY_PATH=/certs/server.key \
  -v /host/path/to/certs:/certs \
  cyborginc/cyborgdb-service:latest

Docker Compose with SSL:

services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_API_KEY=cyborg_your_api_key_here
      - CYBORGDB_DB_TYPE=s3
      - CYBORGDB_S3_BUCKET=cyborgdb-prod
      - CYBORGDB_S3_REGION=us-east-1
      - SSL_CERT_PATH=/certs/server.crt
      - SSL_KEY_PATH=/certs/server.key
    volumes:
      - ./certs:/certs

The server automatically switches to HTTPS when both certificate files are provided and exist. Without certificates, it starts in HTTP mode.

Next Steps

The Python client above is the fastest way to reach a first query. To integrate from another language, install the equivalent client SDK:

npm install cyborgdb

npm install cyborgdb

go get github.com/cyborginc/cyborgdb-go

REST API Reference

Learn how to use the REST API for direct integration

Python SDK Reference

Learn how to use the Python SDK for direct integration

JS/TS SDK Reference

Learn how to use the JavaScript/TypeScript SDK for direct integration

Go SDK Reference

Learn how to use the Go SDK for direct integration

Technical Specifications

Base Image: python:3.11-slim
Python Version: 3.11
PyTorch: CPU-optimized for maximum compatibility
Docker Image Size: ~1.8GB
Platform: linux/amd64, linux/arm64
Default Port: 8000

Comparison with Python Service

Aspect	Python Service	Docker Service
Installation	`pip install`	`docker run`
Dependencies	Managed by pip/conda	Bundled in container
Resource Usage	Lower overhead	Higher overhead
Environment Isolation	Python virtualenv	Container isolation
Deployment Complexity	Simple Python deployment	Container orchestration
Configuration	Environment variables/files	Environment variables
Best For	Development, Python-heavy workflows	Production, cloud deployment

Both approaches provide identical CyborgDB functionality. Choose based on your deployment preferences and infrastructure requirements.

CyborgDB Service

Encrypted Indexes

Data Operations

Advanced

Docker Service Quickstart

Overview

REST API Reference

Python SDK Reference

JS/TS SDK Reference

Go SDK Reference

​Overview

REST API Reference

Python SDK Reference

JS/TS SDK Reference

Go SDK Reference

Overview