Environment Variables

CyborgDB Service uses environment variables to configure various aspects of the service, such as database connections, API keys, SSL settings, and performance tuning. This allows for flexible configuration without hardcoding values in your codebase. Below are the key environment variables you can set for the CyborgDB service:

Required Environment Variables

These environment variables must be set for the service to run:

Variable	Description	Required	Example
`CYBORGDB_API_KEY`	Your CyborgDB API key for authentication	✅	`cyborg_abc123...`

The service requires CYBORGDB_API_KEY to start. Database configuration is optional - see below for details.

Database Configuration

Default Behavior: If you don’t set CYBORGDB_DB_TYPE or CYBORGDB_CONNECTION_STRING, the service automatically uses a built-in standalone instance for evaluation and testing. Data is stored in a ~/.cyborgdb/data directory (local) or /app/cyborgdb_data (Docker).For production deployments, you should configure an external Redis or PostgreSQL database:

Variable	Description	Required	Example
`CYBORGDB_DB_TYPE`	Database backend type	⚠️ Optional (defaults to standalone)	`standalone`, `postgres`, `redis`, or `memory`
`CYBORGDB_CONNECTION_STRING`	Database connection details	⚠️ Optional (defaults to standalone)	See Connection Formats

Important: CYBORGDB_CONNECTION_STRING is required when CYBORGDB_DB_TYPE is set to redis or postgres. For standalone, the connection string is optional and can be used to override the default data directory path. For memory, no connection string is needed.Standalone is for EVALUATION ONLY - For production use, configure an external PostgreSQL or Redis database.

Optional Environment Variables

Service Configuration

Variable	Description	Default	Example
`PORT`	Port number for the service	`8000`	`3000`
`APP_NAME`	Application name for logging	`CyborgDB Service`	`My CyborgDB Instance`
`CYBORGDB_SERVICE_LOG_LEVEL`	Logging level for the service	`info`	`debug`

Security Configuration

Variable	Description	Default	Example
`REQUIRE_API_KEY`	Whether to require API key authentication	`true`	`false`
`SSL_CERT_PATH`	Path to SSL certificate file for HTTPS	`None`	`/etc/ssl/certs/server.crt`
`SSL_KEY_PATH`	Path to SSL private key file for HTTPS	`None`	`/etc/ssl/private/server.key`

When both SSL_CERT_PATH and SSL_KEY_PATH are provided and the files exist, the service automatically enables HTTPS.

Database Configuration (Advanced)

These variables provide granular control over database connections. If not set, they fall back to the main database configuration:

Variable	Description	Default	Example
`INDEX_LOCATION`	Database type for index storage	`CYBORGDB_DB_TYPE`	`standalone`, `postgres`, `redis`, or `memory`
`CONFIG_LOCATION`	Database type for config storage	`CYBORGDB_DB_TYPE`	`standalone`, `postgres`, `redis`, or `memory`
`ITEMS_LOCATION`	Database type for items storage	`CYBORGDB_DB_TYPE`	`standalone`, `postgres`, `redis`, or `memory`
`INDEX_CONNECTION_STRING`	Connection string for index storage	`CYBORGDB_CONNECTION_STRING`	See connection formats
`CONFIG_CONNECTION_STRING`	Connection string for config storage	`CYBORGDB_CONNECTION_STRING`	See connection formats
`ITEMS_CONNECTION_STRING`	Connection string for items storage	`CYBORGDB_CONNECTION_STRING`	See connection formats

Database Table Names

These variables allow you to customize the table/collection names used by the service:

Variable	Description	Default	Example
`INDEX_TABLE_NAME`	Table name for indexes	`index`	`cyborgdb_indexes`
`CONFIG_TABLE_NAME`	Table name for configurations	`config`	`cyborgdb_configs`
`ITEMS_TABLE_NAME`	Table name for items	`items`	`cyborgdb_items`

Performance Tuning

These variables allow you to optimize performance based on your hardware and workload:

Variable	Description	Default	Example
`CPU_THREADS`	Number of CPU threads to use	`0` (auto-detect)	`4`
`GPU_OPERATIONS`	GPU acceleration for specific operations	`none`	`all`
`RETRAIN_THRESHOLD`	Multiplier for automatic retraining threshold	`10000`	`5000`
`WORKERS`	Number of worker processes for handling requests	`0` (auto-calculate)	`8`

GPU_OPERATIONS valid values: none, upsert, train, query, all, or comma-separated (e.g., upsert,train).RETRAIN_THRESHOLD controls when auto-training triggers: training is initiated when num_vectors > n_lists * RETRAIN_THRESHOLD.

System Configuration

These variables control system-level settings:

Variable	Description	Default	Example
`KMP_DUPLICATE_LIB_OK`	Allow duplicate OpenMP libraries	`TRUE`	`FALSE`
`PYTHONUNBUFFERED`	Disable Python output buffering	`1`	`0`

Connection Formats

PostgreSQL Connection String

Use the standard PostgreSQL connection string format:

CYBORGDB_CONNECTION_STRING="host=localhost port=5432 dbname=cyborgdb user=cyborgdb password=your_password"

Parameters:

host - Database server hostname
port - Database server port (default: 5432)
dbname - Database name
user - Database username
password - Database password

Redis Connection String

Use a comma-separated format for Redis connections:

CYBORGDB_CONNECTION_STRING="host:localhost,port:6379,db:0"

Parameters:

host - Redis server hostname
port - Redis server port (default: 6379)
db - Redis database number (default: 0)
password - Redis password (optional)

Redis URI format (redis:// or rediss://) is not supported. Use the comma-separated format shown above.

Standalone Connection String (Optional)

The standalone backend uses a local directory for data storage. A connection string is not required — if omitted, the default path is used.

Local default: ~/.cyborgdb/data
Docker default: /app/cyborgdb_data

To override the data directory path, set the connection string to a custom path:

CYBORGDB_CONNECTION_STRING="/custom/path/to/data"

Configuration Examples

Evaluation/Testing Configuration (Standalone)

# Minimal configuration - uses built-in standalone
export CYBORGDB_API_KEY="cyborg_your_api_key_here"
# No database configuration needed - standalone starts automatically

# Minimal configuration - uses built-in standalone
CYBORGDB_API_KEY=cyborg_your_api_key_here
# No database configuration needed - standalone starts automatically

Standalone is for evaluation and testing only. For production, configure an external database.

Development Configuration (External Database)

export CYBORGDB_API_KEY="cyborg_your_api_key_here"
export CYBORGDB_DB_TYPE="postgres"
export CYBORGDB_CONNECTION_STRING="host=localhost port=5432 dbname=cyborgdb user=cyborgdb password=secure_password"

CYBORGDB_API_KEY=cyborg_your_api_key_here
CYBORGDB_DB_TYPE=postgres
CYBORGDB_CONNECTION_STRING=host=localhost port=5432 dbname=cyborgdb user=cyborgdb password=secure_password

Production Configuration

export CYBORGDB_API_KEY="cyborg_your_api_key_here"
export CYBORGDB_DB_TYPE="postgres"
export CYBORGDB_CONNECTION_STRING="host=db.example.com port=5432 dbname=cyborgdb user=cyborgdb password=secure_password"
export PORT="8443"
export SSL_CERT_PATH="/etc/ssl/certs/cyborgdb.crt"
export SSL_KEY_PATH="/etc/ssl/private/cyborgdb.key"
export WORKERS="16"

CYBORGDB_API_KEY=cyborg_your_api_key_here
CYBORGDB_DB_TYPE=postgres
CYBORGDB_CONNECTION_STRING=host=db.example.com port=5432 dbname=cyborgdb user=cyborgdb password=secure_password
PORT=8443
SSL_CERT_PATH=/etc/ssl/certs/cyborgdb.crt
SSL_KEY_PATH=/etc/ssl/private/cyborgdb.key
WORKERS=16

Mixed Database Configuration

For advanced use cases where you want to use different databases for different components:

# Main configuration
CYBORGDB_API_KEY="cyborg_your_api_key_here"

# Use PostgreSQL for indexes and configs
INDEX_LOCATION="postgres"
CONFIG_LOCATION="postgres"
INDEX_CONNECTION_STRING="host=postgres.example.com port=5432 dbname=cyborgdb user=cyborgdb password=password1"
CONFIG_CONNECTION_STRING="host=postgres.example.com port=5432 dbname=cyborgdb user=cyborgdb password=password1"

# Use Redis for items (faster access)
ITEMS_LOCATION="redis"
ITEMS_CONNECTION_STRING="host:redis.example.com,port:6379,db:0,password:redis_password"

Docker Configuration

When using Docker, you can pass environment variables using the -e flag:

docker run -p 8000:8000 \
  -e CYBORGDB_API_KEY="cyborg_your_api_key_here" \
  -e CYBORGDB_DB_TYPE="postgres" \
  -e CYBORGDB_CONNECTION_STRING="host=host.docker.internal port=5432 dbname=cyborgdb user=cyborgdb password=secure_password" \
  cyborginc/cyborgdb-service:latest

Or use an environment file:

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

Environment Variable Priority

Environment variables are loaded in the following order (later sources override earlier ones):

Default values - Set in the application code
.env file - Local environment file in the working directory
System environment variables - Set via export or container environment
Command line arguments - Passed directly to the application

Validation and Error Handling

The CyborgDB service performs automatic validation of environment variables on startup:

Missing required variables - Service will exit with error messages
Invalid database types - Supported types are standalone, postgres, redis, and memory
Connection testing - Database connections are tested on startup
SSL certificate validation - Certificate files are checked for existence

If validation fails, the service will display helpful error messages with examples of correct configuration.

Troubleshooting

Missing API Key

Ensure CYBORGDB_API_KEY is set
Check for typos in the variable name
Verify the API key format starts with cyborg_

Database Connection Issues

Verify database is running and accessible
Check connection string format
Test database connectivity manually
Ensure firewall allows connections

SSL Certificate Errors

Verify certificate files exist at specified paths
Check file permissions (service must be able to read certificates)
Ensure certificate and key files match
Use absolute paths for certificate locations

CyborgDB Service

Encrypted Indexes

Data Operations

Advanced

Required Environment Variables

Database Configuration

Optional Environment Variables

Connection Formats

Configuration Examples

Docker Configuration

Environment Variable Priority

Validation and Error Handling

Troubleshooting

​Required Environment Variables

​Database Configuration

​Optional Environment Variables

​Connection Formats

​Configuration Examples

​Docker Configuration

​Environment Variable Priority

​Validation and Error Handling

​Troubleshooting

Required Environment Variables

Database Configuration

Optional Environment Variables

Connection Formats

Configuration Examples

Docker Configuration

Environment Variable Priority

Validation and Error Handling

Troubleshooting