cyborgdb-service 0.17.0

REST Server for CyborgDB: The Confidential Vector Database

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. Run it yourself 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 (see BYOK.md)
• Per-tenant key isolation: Per-index, per-user keys with cryptographic RBAC; revoke a user and their keys are erased
• Multiple backing stores: Embedded RocksDB disk, AWS S3 / S3-compatible object storage (MinIO etc.), or in-memory

Getting Started

To get started in minutes, check out our Quickstart Guide.

Installation

1. Install cyborgdb-service

pip install cyborgdb-service
# GPU (CUDA 12): pip install cyborgdb-service-cu12

2. [Optional] Set an API key for unlimited usage — without one the service runs in free-tier mode (per-index cap of 1M items)

export CYBORGDB_API_KEY=your_api_key_here   # optional; unset runs free tier

3. [Optional] Choose a storage backend (default: disk at ~/.cyborgdb/data)

export CYBORGDB_DB_TYPE='memory|disk|s3'   # default: disk
export CYBORGDB_DISK_PATH=/path/to/data    # disk only; default ~/.cyborgdb/data
export CYBORGDB_S3_BUCKET=my-bucket        # s3 only (required)

Tip: Run cyborgdb-service --help for a detailed list of all configuration options.

4. Run the server

cyborgdb-service

Storage Backends

Backend	Select with	Notes
Disk (default)	CYBORGDB_DB_TYPE=disk	Embedded RocksDB. CYBORGDB_DISK_PATH sets the data directory (default ~/.cyborgdb/data).
In-memory	CYBORGDB_DB_TYPE=memory	No persistence across restarts.
S3	CYBORGDB_DB_TYPE=s3	Requires CYBORGDB_S3_BUCKET. Optional: CYBORGDB_S3_REGION, CYBORGDB_S3_PREFIX, CYBORGDB_S3_ENDPOINT.

S3 credentials

Each AWS-touching client (S3 storage, KMS) resolves credentials independently:

• On AWS (ECS/EC2/EKS) — set nothing; the AWS default credential provider chain picks up the instance/task role.
• Off AWS, real S3 — provide AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars or a mounted AWS profile; the default chain picks them up.
• S3-compatible endpoint (MinIO etc.) — set CYBORGDB_S3_ENDPOINT plus explicit CYBORGDB_S3_ACCESS_KEY / CYBORGDB_S3_SECRET_KEY (and optionally CYBORGDB_S3_SESSION_TOKEN). A custom endpoint is not AWS: the AWS chain is never used against it, and startup fails fast if the explicit keys are missing. The CYBORGDB_S3_* namespace is kept separate from AWS_* so storage credentials can't collide with KMS credentials.

YAML Configuration File (optional)

Everything settable by environment variable can also live in a YAML file — see cyborgdb.example.yaml. The file is resolved from CYBORGDB_CONFIG_FILE, then ./cyborgdb.yaml, ./cyborgdb.yml, /etc/cyborgdb/cyborgdb.yaml. Environment variables override the file on conflict. The YAML file is also where the per-index KMS registry (kms.registry:) is configured.

API Key Configuration

The CYBORGDB_API_KEY is the cyborgdb-core license key (not a service-auth credential). It is optional — when unset, the service runs in free-tier mode (per-index cap of 1M items). To unlock unlimited usage, provide your key using any of these methods:

Method 1: Environment Variable (Easiest)

export CYBORGDB_API_KEY=your_api_key_here
cyborgdb-service

Method 2: .env File

Create a .env file in the project root:

CYBORGDB_API_KEY=your_api_key_here

Then run:

cyborgdb-service

Method 3: Inline with Launch

CYBORGDB_API_KEY=your_api_key_here cyborgdb-service

Service Authentication

Request authentication is controlled by CYBORGDB_SERVICE_ROOT_KEY — separate from the CYBORGDB_API_KEY license key above:

• Unset (default): authentication is disabled and the service accepts every request. Do not run a network-exposed deployment this way.
• Set: authentication is enabled. Clients must send the key in the X-API-Key header. Routes accept the root key or a cdbk_ user token minted under it, and the root key can mint per-user API keys.

export CYBORGDB_SERVICE_ROOT_KEY=your_root_key_here
# then call the API with:  -H "X-API-Key: your_root_key_here"

Documentation

For more information on CyborgDB, see the Cyborg Docs.

License

CyborgDB Service is licensed under the MIT License. The underlying library, CyborgDB Core, is licensed under Cyborg's Terms of Service.