Environment Variables

CyborgDB Service is configured through environment variables (or an optional YAML config file). Every value below is settable in both places; environment variables override the file on conflict.

Storage surface. The service exposes a single, flat storage surface: disk or s3 (AWS S3 or any S3-compatible store). Configure it with CYBORGDB_DB_TYPE plus the matching CYBORGDB_DISK_PATH / CYBORGDB_S3_* variables.

API Key and Tiers

Variable	Description	Example
`CYBORGDB_API_KEY`	(Optional) Your CyborgDB license key, forwarded to the core engine. If unset, the service runs in free tier mode (per-index cap of 1,000,000 items). Set a paid key for unlimited usage. This is not a service-authentication credential — it does not gate access to the REST API.	`cyborg_abc123...`

Free tier vs paid. CYBORGDB_API_KEY is the single switch between the two:

Unset → free tier. cyborgdb-core enforces a 1M-item-per-index cap. At startup the service logs CYBORGDB_API_KEY not set — the service will run in free tier. For evaluation only.
Set to a paid key (from the CyborgDB dashboard) → unlimited items, full feature set.
Set to a demo key (from cyborgdb.get_demo_api_key() / getDemoApiKey() / cyborgdb.GetDemoAPIKey(...)) → also free tier, time-limited. Useful for evaluating without dashboard signup.

This key controls licensing only. Request authentication is a separate concern, gated by CYBORGDB_SERVICE_ROOT_KEY (see RBAC / Multi-Tenancy).

Storage configuration is optional — disk is used by default.

RBAC / Multi-Tenancy

CYBORGDB_SERVICE_ROOT_KEY is the single source of truth for request authentication. Leave it unset (the default) and authentication is disabled — every request is accepted, and the service logs a startup warning to that effect. Set it and authentication turns on: routes then accept only the root key or a per-user cdbk_… token minted under it, sent in the X-API-Key header.

Variable	Description	Default
`CYBORGDB_SERVICE_ROOT_KEY`	When set, enables authentication and RBAC. The holder of this key has full admin access and can mint per-user API keys via `POST /v1/indexes/{index_name}/users`. Per-user keys are scoped to one index with `read` / `write` permissions enforced cryptographically. When unset, authentication is disabled.	unset (auth off)
`INDEX_KEK_CACHE_TTL_SECONDS`	TTL for plaintext index KEKs in the service-side cache. Shorter = faster KMS revocation propagation; longer = fewer KMS calls.	`60`

See the Multi-Tenancy guide for the full operator playbook (key kinds, provisioning users, SDK-supplied indexes, revocation).

Embedding Model Cache

Text embedding_model indexes resolve and download their model on first use. These variables control where the model is cached and whether a cache miss is allowed to reach the model hub.

Variable	Description	Default
`CYBORGDB_EMBED_CACHE`	Directory where downloaded embedding models are cached. Mount this on persistent storage so models survive container restarts.	`/app/cyborgdb_data/embed-cache` in Docker; otherwise the embedding backend’s default cache location
`CYBORGDB_EMBED_OFFLINE`	When set to `1`, the service never calls out to the model hub. A cache miss fails the request instead of downloading. Set this on air-gapped deployments after pre-populating `CYBORGDB_EMBED_CACHE`.	unset (downloads allowed)

When a model is unavailable — the hub is unreachable, or CYBORGDB_EMBED_OFFLINE=1 and the model is not in the cache — upsert and query calls that embed contents/query_contents return HTTP 503 with a Retry-After: 30 header. Calls on pre-computed vectors are unaffected.

# Air-gapped: pre-populate the cache, then forbid downloads
export CYBORGDB_EMBED_CACHE=/var/lib/cyborgdb/embed-cache
export CYBORGDB_EMBED_OFFLINE=1

List the models the service currently supports with GET /v1/embedding-models.

Storage Backend

Pick either disk or s3. If CYBORGDB_DB_TYPE is unset, the service defaults to disk.

Variable	Description	Default	Example
`CYBORGDB_DB_TYPE`	Storage backend: `disk` or `s3`	`disk`	`s3`

Disk (default)

Persistent local key-value storage with no external dependency.

Variable	Description	Default
`CYBORGDB_DISK_PATH`	Data directory for the disk store	`~/.cyborgdb/data` (local) / `/app/cyborgdb_data` (Docker)

export CYBORGDB_DB_TYPE=disk
export CYBORGDB_DISK_PATH=/var/lib/cyborgdb   # optional

S3

AWS S3 or any S3-compatible store (MinIO, Cloudflare R2, …).

Variable	Description	Required for S3
`CYBORGDB_S3_BUCKET`	Bucket name	✅
`CYBORGDB_S3_REGION`	Bucket region	Optional (defaults to `us-east-1`)
`CYBORGDB_S3_PREFIX`	Key prefix for stored objects	Optional
`CYBORGDB_S3_ENDPOINT`	Custom endpoint URL (MinIO, R2, …)	Required for non-AWS endpoints
`CYBORGDB_S3_ACCESS_KEY`	S3 access key ID	Required with `CYBORGDB_S3_ENDPOINT`
`CYBORGDB_S3_SECRET_KEY`	S3 secret access key	Required with `CYBORGDB_S3_ENDPOINT`
`CYBORGDB_S3_SESSION_TOKEN`	Optional temporary session token	Optional

S3 credential resolution

The S3 client resolves credentials independently of any KMS client:

On AWS (EC2 / ECS / EKS), real S3. Leave all CYBORGDB_S3_* credential variables unset. 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 (or a mounted AWS profile). The default chain picks them up.
S3-compatible endpoint (MinIO, R2, …). Set CYBORGDB_S3_ENDPOINT plus explicit CYBORGDB_S3_ACCESS_KEY / CYBORGDB_S3_SECRET_KEY. 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 deliberately separate from AWS_* so storage credentials cannot collide with KMS credentials.

# AWS S3 with instance role
export CYBORGDB_DB_TYPE=s3
export CYBORGDB_S3_BUCKET=my-bucket
export CYBORGDB_S3_REGION=us-east-1

# MinIO
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 Environment Variables

Service Configuration

Variable	Description	Default
`PORT`	HTTP port for the service	`8000`
`CYBORGDB_SERVICE_LOG_LEVEL`	Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`

Request authentication is controlled solely by CYBORGDB_SERVICE_ROOT_KEY (see RBAC / Multi-Tenancy). When it is unset, authentication is disabled and every request is accepted — the service logs a startup warning. When it is set, clients must send the root key or a cdbk_ user token in the X-API-Key header, or the request is rejected with 401. This is independent of the free-tier / paid-tier distinction, which is gated only by CYBORGDB_API_KEY.

TLS / HTTPS

Variable	Description	Default
`SSL_CERT_PATH`	Path to TLS certificate	unset (HTTP)
`SSL_KEY_PATH`	Path to TLS private key	unset (HTTP)

HTTPS is enabled automatically when both SSL_CERT_PATH and SSL_KEY_PATH are set and both files exist. Otherwise the service starts on HTTP.

Per-keystore RAM cache

Applied to every newly created index. cyborgdb-core caches nothing by default; opt in here per keystore.

Variable	Description	Default
`CACHE_POLICY_VECTORS`	Cache vector payloads in RAM	`false`
`CACHE_POLICY_METADATA`	Cache metadata in RAM	`false`
`CACHE_POLICY_IDS`	Cache item IDs in RAM	`false`

Performance

Variable	Description	Default
`CPU_THREADS`	Worker threads. `0` = auto-detect	`0`
`GPU_OPERATIONS`	GPU-accelerated ops: `none`, `upsert`, `train`, `all`, or comma-separated (e.g. `upsert,train`)	`none`
`AUTO_TRAIN_MIN_VECTORS`	An untrained index is trained automatically once it holds more than this many vectors. Trained indexes are retrained automatically as they grow; see How automatic training works.	`65536`
`AUTO_TRAIN_DISABLED`	Fully disable post-upsert auto-training and retraining. Explicit `train()` / `POST /v1/indexes/train` still work. Useful for benchmarking a fixed index state or controlling training timing yourself.	`false`

GPU-accelerated query is not yet supported by cyborgdb-core. Passing query in GPU_OPERATIONS is silently ignored.

Per-index KMS

Per-index KMS (BYOK) is configured exclusively via the YAML file’s kms.registry block — see the KMS / BYOK guide. The related environment variable is documented above under RBAC / Multi-Tenancy (INDEX_KEK_CACHE_TTL_SECONDS).

YAML Configuration File

Every setting above is also expressible in a YAML file. The file is resolved in this order (first hit wins):

CYBORGDB_CONFIG_FILE environment variable
./cyborgdb.yaml, ./cyborgdb.yml, /etc/cyborgdb/cyborgdb.yaml

A missing file is fine — the service falls back to env-only. An explicit CYBORGDB_CONFIG_FILE path that doesn’t exist is a hard error.

cyborgdb.yaml

service:
  port: 8000
  cyborgdb_service_log_level: INFO

  # Optional: enable RBAC by setting a root API key. See ./multi-tenancy.
  # cyborgdb_service_root_key: ${CYBORGDB_SERVICE_ROOT_KEY}

  # Storage backend: disk | s3 (default: disk)
  cyborgdb_db_type: disk
  # cyborgdb_disk_path: /var/lib/cyborgdb

  # S3 settings (when cyborgdb_db_type: s3)
  # cyborgdb_s3_bucket: my-bucket
  # cyborgdb_s3_region: us-east-1
  # cyborgdb_s3_endpoint: https://minio.internal:9000
  # cyborgdb_s3_access_key: ${MINIO_ACCESS_KEY}
  # cyborgdb_s3_secret_key: ${MINIO_SECRET_KEY}

  cpu_threads: 0
  index_kek_cache_ttl_seconds: 60

kms:
  registry:
    # See the KMS / BYOK guide for the full schema.
    # vendor-default:
    #   provider: aws-kms
    #   key_id:   alias/cyborgdb-default
    #   region:   us-east-1

Precedence: environment variables > .env > YAML file. Env-var substitution. Any string value in the YAML may reference an environment variable as ${VAR} (required — startup fails if unset) or ${VAR:-default} (uses default when unset). This lets you keep BYOK role ARNs / account IDs out of the checked-in file. A variable set to the empty string counts as unset.

Configuration Examples

Quick start (disk, default)

export CYBORGDB_API_KEY="cyborg_your_api_key_here"
cyborgdb-service
# Data goes to ~/.cyborgdb/data

S3 on AWS with instance role

export CYBORGDB_API_KEY="cyborg_your_api_key_here"
export CYBORGDB_DB_TYPE=s3
export CYBORGDB_S3_BUCKET=my-bucket
export CYBORGDB_S3_REGION=us-east-1
# No explicit credentials — instance role picked up automatically
cyborgdb-service

S3 on MinIO with explicit credentials

export 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
cyborgdb-service

Production with HTTPS

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 PORT=8443
export SSL_CERT_PATH=/etc/ssl/certs/cyborgdb.crt
export SSL_KEY_PATH=/etc/ssl/private/cyborgdb.key
cyborgdb-service

Docker

Pass any of the variables above to docker run with -e:

docker run -p 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

Or use an --env-file:

docker run -p 8000:8000 --env-file .env cyborginc/cyborgdb-service:latest

Troubleshooting

Missing API key

Set CYBORGDB_API_KEY. Check for typos. Keys start with cyborg_.

Invalid CYBORGDB_DB_TYPE

CyborgDB accepts disk or s3. Set CYBORGDB_DISK_PATH if you use a custom directory for the disk store.

S3 startup fails with missing credentials

With CYBORGDB_S3_ENDPOINT set, the AWS default credential chain is bypassed entirely. Provide CYBORGDB_S3_ACCESS_KEY and CYBORGDB_S3_SECRET_KEY explicitly.

TLS not enabling

Both SSL_CERT_PATH and SSL_KEY_PATH must be set and both files must exist on disk before the service starts. Missing either falls back to HTTP silently.

CyborgDB Service

Encrypted Indexes

Data Operations

Advanced

API Key and Tiers

RBAC / Multi-Tenancy

Embedding Model Cache

Storage Backend

Disk (default)

S3

S3 credential resolution

Optional Environment Variables

YAML Configuration File

Configuration Examples

Docker

Troubleshooting

​API Key and Tiers

​RBAC / Multi-Tenancy

​Embedding Model Cache

​Storage Backend

​Disk (default)

​S3

​S3 credential resolution

​Optional Environment Variables

​YAML Configuration File

​Configuration Examples

​Docker

​Troubleshooting

API Key and Tiers

RBAC / Multi-Tenancy

Embedding Model Cache

Storage Backend

Disk (default)

S3

S3 credential resolution

Optional Environment Variables

YAML Configuration File

Configuration Examples

Docker

Troubleshooting