Environment Variables - CyborgDB Docs

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.

v0.17 storage refactor. The service now exposes a single, flat storage surface: memory, disk (embedded RocksDB), or s3 (AWS S3 or any S3-compatible store). The previous standalone, postgres, and redis backends — and the catch-all CYBORGDB_CONNECTION_STRING — are gone. If you are upgrading from v0.16: switch standalone → disk and replace CYBORGDB_CONNECTION_STRING with the new 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, KMS-backed constraint, revocation).

Storage Backend

Pick one of memory, disk, or s3. If CYBORGDB_DB_TYPE is unset, the service defaults to disk.

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

Disk (default)

Embedded RocksDB. Persistent local key-value storage with no external dependency.

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

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

Memory

In-process storage. Nothing persists across restarts. Use only for tests and ephemeral indexes.

export CYBORGDB_DB_TYPE=memory

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`
`RETRAIN_THRESHOLD`	Auto-retrain trigger — fires when `num_vectors > n_lists * RETRAIN_THRESHOLD`	`10000`
`AUTO_TRAIN_DISABLED`	Fully disable post-upsert auto-training. Explicit `train()` / `POST /v1/indexes/train` still work. Useful for benchmarking a fixed index state or controlling training timing yourself. Also implied when `RETRAIN_THRESHOLD < 0`.	`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
  require_api_key: true
  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: memory | 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: init args > environment variables > .env > YAML file > file secrets. 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

In-memory (tests only)

export CYBORGDB_API_KEY="cyborg_your_api_key_here"
export CYBORGDB_DB_TYPE=memory
cyborgdb-service

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`

v0.17 only accepts memory, disk, or s3. The legacy standalone, postgres, and redis values are gone. If you were on standalone, switch to disk and set CYBORGDB_DISK_PATH if you used a custom directory.

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.

​API Key and Tiers

​RBAC / Multi-Tenancy

​Storage Backend

​Disk (default)

​Memory

​S3

​S3 credential resolution

​Optional Environment Variables

​YAML Configuration File

​Configuration Examples

​Docker

​Troubleshooting

API Key and Tiers

RBAC / Multi-Tenancy

Storage Backend

Disk (default)

Memory

S3

S3 credential resolution

Optional Environment Variables

YAML Configuration File

Configuration Examples

Docker

Troubleshooting