Python Service Quickstart

CyborgDB can be deployed as a Python service using pip installation. This approach provides a lightweight alternative to Docker, allowing you to run the CyborgDB service directly in your Python environment with full control over dependencies and configuration.

Looking to use Docker? Check out our Docker Quickstart Guide.

Overview

The Python service is ideal for developers who prefer managing Python environments directly, need custom dependency management, or want to integrate CyborgDB service into existing Python applications. It provides the same REST API functionality as the Docker version.

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.

Check Prerequisites

Ensure you have the required Python version and environment tools:

Python: 3.10, 3.11, 3.12, 3.13, or 3.14
Package Manager: conda (recommended) or pip with virtual environment

While conda is mentioned in the build instructions, the wheel works with any Python environment manager including pip, pipenv, poetry, etc.

Choose Your Storage Backend (Optional)

The service ships with three storage backends. Skip this step and you get disk by default — the data directory is ~/.cyborgdb/data.

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

For full details, see the Backing Stores guide.

Install CyborgDB Service

Install the CyborgDB service package using conda and pip:

# Create conda environment
conda create -n cyborgdb-service python=3.12
conda activate cyborgdb-service

# Install the service
pip install cyborgdb-service

# If you want to use automatic embedding generation, install with:
pip install cyborgdb-service[embeddings]

# Create a virtual environment
python -m venv cyborgdb-env
source cyborgdb-env/bin/activate

# Install the service
pip install cyborgdb-service

# Install directly (not recommended for production)
pip install cyborgdb-service

Using conda or a virtual environment is strongly recommended to avoid dependency conflicts with other Python packages.

Configure Environment Variables

Set the required environment variables for your deployment:

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

No environment variables are required — disk is the default and data goes to ~/.cyborgdb/data. Set these only to override the defaults:

# Optional: lift the free-tier 1M-items-per-index cap
# export CYBORGDB_API_KEY=cyborg_your_api_key_here
# Optional: pin the data directory
# export CYBORGDB_DISK_PATH=/var/lib/cyborgdb

# CYBORGDB_API_KEY=cyborg_your_api_key_here
# CYBORGDB_DISK_PATH=/var/lib/cyborgdb

export CYBORGDB_DB_TYPE=memory
# Optional: lift the free-tier 1M-items-per-index cap
# export CYBORGDB_API_KEY=cyborg_your_api_key_here

CYBORGDB_DB_TYPE=memory
# CYBORGDB_API_KEY=cyborg_your_api_key_here

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

export CYBORGDB_DB_TYPE=s3
export CYBORGDB_S3_BUCKET=my-bucket
export CYBORGDB_S3_REGION=us-east-1
# Optional: lift the free-tier 1M-items-per-index cap
# export CYBORGDB_API_KEY=cyborg_your_api_key_here
# On EC2/ECS/EKS the instance role is picked up automatically.
# Off AWS, set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY instead.

CYBORGDB_DB_TYPE=s3
CYBORGDB_S3_BUCKET=my-bucket
CYBORGDB_S3_REGION=us-east-1
# CYBORGDB_API_KEY=cyborg_your_api_key_here

export CYBORGDB_DB_TYPE=s3
export CYBORGDB_S3_BUCKET=my-bucket
export CYBORGDB_S3_ENDPOINT=https://minio.internal:9000
export CYBORGDB_S3_ACCESS_KEY=minioadmin
export CYBORGDB_S3_SECRET_KEY=minioadmin
# Optional: lift the free-tier 1M-items-per-index cap
# export CYBORGDB_API_KEY=cyborg_your_api_key_here

CYBORGDB_DB_TYPE=s3
CYBORGDB_S3_BUCKET=my-bucket
CYBORGDB_S3_ENDPOINT=https://minio.internal:9000
CYBORGDB_S3_ACCESS_KEY=minioadmin
CYBORGDB_S3_SECRET_KEY=minioadmin
# CYBORGDB_API_KEY=cyborg_your_api_key_here

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

Using a .env file is the most convenient method as it persists your configuration and keeps sensitive data out of your shell history.

For more information on environment variables, refer to this guide.

Start the Service

Run the CyborgDB service using the installed command:

cyborgdb-service

The service will start and display startup information including:

Configured storage backend (memory, disk, or s3)
Server URL (default: http://localhost:8000)
Available API endpoints

For additional configuration options, run cyborgdb-service --help to see all available command-line arguments.

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
Production Deployment
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 service starts with no configuration, using disk storage rooted at ~/.cyborgdb/data, free-tier licensing, and authentication disabled. For the full list (including S3 credentials and KMS), see the Environment Variables guide.

For production environments, consider using a process manager:

# Using gunicorn (install separately)
pip install gunicorn
gunicorn cyborgdb_service.main:app --port 8000

# Using systemd service (Linux)
sudo systemctl enable cyborgdb-service
sudo systemctl start cyborgdb-service

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

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

Complete Production Example:

# Set all required environment variables including SSL
export CYBORGDB_API_KEY=cyborg_your_api_key_here
export CYBORGDB_DB_TYPE=s3
export CYBORGDB_S3_BUCKET=cyborgdb-prod
export CYBORGDB_S3_REGION=us-east-1
export SSL_CERT_PATH=/etc/ssl/certs/server.crt
export SSL_KEY_PATH=/etc/ssl/private/server.key

# Start service (will automatically use HTTPS)
cyborgdb-service

Using .env File with SSL:

# Create a .env file with SSL configuration
cat > .env << EOF
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=/path/to/certificate.crt
SSL_KEY_PATH=/path/to/private.key
EOF

# Start service
cyborgdb-service

Using Let’s Encrypt (Production):

# Install certbot (Ubuntu/Debian)
sudo apt-get install certbot

# Generate certificate for your domain
sudo certbot certonly --standalone -d your-domain.com

# Set environment variables to Let's Encrypt certificates
export SSL_CERT_PATH=/etc/letsencrypt/live/your-domain.com/fullchain.pem
export SSL_KEY_PATH=/etc/letsencrypt/live/your-domain.com/privkey.pem

# Start service with HTTPS
cyborgdb-service

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

Comparison with Docker 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

Python 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