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.
1

Get an API Key

To use CyborgDB, you need an API key. You can get one from the CyborgDB Admin Dashboard.Make sure to keep your API key secure and do not share it publicly.
2

Check Prerequisites

Ensure you have the required Python version and environment tools:
  • Python: 3.9, 3.10, 3.11, 3.12, or 3.13
  • Package Manager: conda (recommended) or pip with virtual environment
  • Database: PostgreSQL or Redis instance (local or managed)
While conda is mentioned in the build instructions, the wheel works with any Python environment manager including pip, pipenv, poetry, etc.
3

Choose Your Database Backend

CyborgDB service supports two database backends - choose based on your existing infrastructure:
  • PostgreSQL: Compatible with your existing PostgreSQL infrastructure
    • Managed services: AWS RDS, Azure Database for PostgreSQL, Google Cloud SQL, DigitalOcean Managed Databases
    • Self-hosted PostgreSQL instances
  • Redis: Compatible with your existing Redis infrastructure
    • Managed services: AWS ElastiCache, Azure Cache for Redis, Google Cloud Memorystore, Redis Cloud
    • Self-hosted Redis instances
All backends provide identical CyborgDB functionality. For more info, refer to this guide.
Make sure you have your chosen database running and accessible before proceeding.
4

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]
Using conda or a virtual environment is strongly recommended to avoid dependency conflicts with other Python packages.
5

Configure Environment Variables

Set the required environment variables for your database backend:
export CYBORGDB_API_KEY=cyborg_your_api_key_here
export CYBORGDB_DB_TYPE=postgres
export CYBORGDB_CONNECTION_STRING="host=localhost port=5432 dbname=postgres user=postgres password=your_password"
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 the this guide.
6

Start the Service

Run the CyborgDB service using the installed command:
cyborgdb-service
The service will start and display startup information including:
  • Database connection status
  • Server URL (default: http://localhost:8000)
  • Available API endpoints
For additional configuration options, run cyborgdb-service --help to see all available command-line arguments and connection string examples.
7

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/docs to explore the interactive API documentation.You should see a response indicating the service is healthy and ready to accept requests.
8

Advanced Configuration

For production deployments, consider these additional configurations:
VariableDescriptionRequiredExample
CYBORGDB_API_KEYYour CyborgDB API key✅cyborg_abc123...
CYBORGDB_DB_TYPEDatabase backend type✅postgres or redis
CYBORGDB_CONNECTION_STRINGDatabase connection details✅See connection formats
CYBORGDB_VERSIONService version (optional)❌0.11.1
PORTService port❌8000
SSL_CERT_PATHPath to SSL certificate file❌/etc/ssl/certs/server.crt
SSL_KEY_PATHPath to SSL private key file❌/etc/ssl/private/server.key
For more information on environment variables, refer to the this guide.
9

Next Steps

Now that your CyborgDB service is running, you can interact with it using client SDKs:Install Client SDKs:
pip install cyborgdb

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