> ## Documentation Index
> Fetch the complete documentation index at: https://cyborg-rid-of-c---conan.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Service Quickstart

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

<Tip>Looking to use Docker? Check out our [Docker Quickstart Guide](./quickstart-docker).</Tip>

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

<Steps>
  <Step title="Get an API Key (Optional)">
    The service runs without an API key — leave `CYBORGDB_API_KEY` unset and the core engine starts in free-tier mode, capped at 1,000,000 items per index. Set it to lift that cap. Get a key from the [CyborgDB Admin Dashboard](https://cyborgdb.co/), or generate a temporary demo key with any of the SDKs:

    <CodeGroup>
      ```python Python theme={null}
      import cyborgdb
      print(cyborgdb.get_demo_api_key())
      ```

      ```javascript JavaScript theme={null}
      import { getDemoApiKey } from 'cyborgdb';
      console.log(await getDemoApiKey());
      ```

      ```go Go theme={null}
      demoKey, _ := cyborgdb.GetDemoAPIKey("my demo app")
      fmt.Println(demoKey)
      ```
    </CodeGroup>

    Pass the key as `CYBORGDB_API_KEY` when starting the service. This is the core license key, not a service-authentication credential — it does not gate access to the REST API.

    <Note>
      Service authentication is separate and controlled by `CYBORGDB_SERVICE_ROOT_KEY`. Leave it unset (the default) and the service accepts all requests. Set it to require callers to send the root key — or a `cdbk_` user token minted under it — in the `X-API-Key` header. See [Managing Keys](../advanced/managing-keys).
    </Note>
  </Step>

  <Step title="Check Prerequisites">
    Ensure you have the required Python version and environment tools:

    * **Python**: 3.10, 3.11, 3.12, 3.13, or 3.14
    * **Package Manager**: conda (recommended) or pip with virtual environment

    <Note>While conda is mentioned in the build instructions, the wheel works with any Python environment manager including pip, pipenv, poetry, etc.</Note>
  </Step>

  <Step title="Choose Your Storage Backend (Optional)">
    The service ships with three storage backends. Skip this
    step and you get **disk** (embedded RocksDB) by default —
    the data directory is `~/.cyborgdb/data`.

    * **Disk** (default) — embedded RocksDB on local disk. Persistent,
      no external dependencies. Best for single-node deployments and
      edge devices.
    * **S3** — AWS S3 or any S3-compatible store (MinIO,
      Cloudflare R2, …). Best for cloud-native and multi-node
      deployments.
    * **Memory** — in-process only, nothing persists across
      restarts. For tests and ephemeral indexes.

    For full details, see the [Backing Stores guide](../../../intro/backing-stores).

    <Note>v0.17 collapsed the storage surface. The previous `standalone`, `postgres`, and `redis` backends and the catch-all `CYBORGDB_CONNECTION_STRING` are gone — switch `standalone` → `disk` and use the new `CYBORGDB_DISK_PATH` / `CYBORGDB_S3_*` variables.</Note>
  </Step>

  <Step title="Install CyborgDB Service">
    Install the CyborgDB service package using conda and pip:

    <CodeGroup>
      ```bash Conda Environment (Recommended) theme={null}
      # 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]
      ```

      ```bash Virtual Environment theme={null}
      # Create a virtual environment
      python -m venv cyborgdb-env
      source cyborgdb-env/bin/activate

      # Install the service
      pip install cyborgdb-service
      ```

      ```bash System Python theme={null}
      # Install directly (not recommended for production)
      pip install cyborgdb-service
      ```
    </CodeGroup>

    <Warning>Using conda or a virtual environment is strongly recommended to avoid dependency conflicts with other Python packages.</Warning>
  </Step>

  <Step title="Configure Environment Variables">
    Set the required environment variables for your deployment:

    <Tabs>
      <Tab title="Disk (default)">
        No environment variables are required — disk is the default and data goes to `~/.cyborgdb/data`. Set these only to override the defaults:

        <CodeGroup>
          ```bash Linux/macOS theme={null}
          # Optional: lift the free-tier 1M-items-per-index cap
          # export CYBORGDB_API_KEY=cyborg_your_api_key_here
          # Optional: pin the data directory
          # export CYBORGDB_DISK_PATH=/var/lib/cyborgdb
          ```

          ```bash .env File theme={null}
          # CYBORGDB_API_KEY=cyborg_your_api_key_here
          # CYBORGDB_DISK_PATH=/var/lib/cyborgdb
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Memory">
        <CodeGroup>
          ```bash Linux/macOS theme={null}
          export CYBORGDB_DB_TYPE=memory
          # Optional: lift the free-tier 1M-items-per-index cap
          # export CYBORGDB_API_KEY=cyborg_your_api_key_here
          ```

          ```bash .env File theme={null}
          CYBORGDB_DB_TYPE=memory
          # CYBORGDB_API_KEY=cyborg_your_api_key_here
          ```
        </CodeGroup>

        <Warning>Memory storage does not persist across restarts. Use for tests and ephemeral indexes only.</Warning>
      </Tab>

      <Tab title="S3 (AWS)">
        <CodeGroup>
          ```bash Linux/macOS theme={null}
          export CYBORGDB_DB_TYPE=s3
          export CYBORGDB_S3_BUCKET=my-bucket
          export CYBORGDB_S3_REGION=us-east-1
          # Optional: lift the free-tier 1M-items-per-index cap
          # export CYBORGDB_API_KEY=cyborg_your_api_key_here
          # On EC2/ECS/EKS the instance role is picked up automatically.
          # Off AWS, set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY instead.
          ```

          ```bash .env File theme={null}
          CYBORGDB_DB_TYPE=s3
          CYBORGDB_S3_BUCKET=my-bucket
          CYBORGDB_S3_REGION=us-east-1
          # CYBORGDB_API_KEY=cyborg_your_api_key_here
          ```
        </CodeGroup>
      </Tab>

      <Tab title="S3 (MinIO / R2)">
        <CodeGroup>
          ```bash Linux/macOS theme={null}
          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: lift the free-tier 1M-items-per-index cap
          # export CYBORGDB_API_KEY=cyborg_your_api_key_here
          ```

          ```bash .env File theme={null}
          CYBORGDB_DB_TYPE=s3
          CYBORGDB_S3_BUCKET=my-bucket
          CYBORGDB_S3_ENDPOINT=https://minio.internal:9000
          CYBORGDB_S3_ACCESS_KEY=minioadmin
          CYBORGDB_S3_SECRET_KEY=minioadmin
          # CYBORGDB_API_KEY=cyborg_your_api_key_here
          ```
        </CodeGroup>

        <Note>With a custom `CYBORGDB_S3_ENDPOINT` the AWS default credential chain is bypassed entirely — `CYBORGDB_S3_ACCESS_KEY` / `CYBORGDB_S3_SECRET_KEY` are required.</Note>
      </Tab>
    </Tabs>

    <Tip>Using a `.env` file is the most convenient method as it persists your configuration and keeps sensitive data out of your shell history.</Tip>

    For more information on environment variables, refer to [this guide](../advanced/env-vars).
  </Step>

  <Step title="Start the Service">
    Run the CyborgDB service using the installed command:

    ```bash theme={null}
    cyborgdb-service
    ```

    The service will start and display startup information including:

    * Configured storage backend (`memory`, `disk`, or `s3`)
    * Server URL (default: `http://localhost:8000`)
    * Available API endpoints

    <Note>For additional configuration options, run `cyborgdb-service --help` to see all available command-line arguments.</Note>
  </Step>

  <Step title="Verify Installation">
    Once the service is running, verify it's working correctly:

    **Health Check:**

    ```bash theme={null}
    curl http://localhost:8000/v1/health
    ```

    **API Documentation:**
    Navigate to [http://localhost:8000/v1/docs](http://localhost:8000/v1/docs) to explore the interactive API documentation.

    You should see a response indicating the service is healthy and ready to accept requests.
  </Step>

  <Step title="Advanced Configuration">
    For production deployments, consider these additional configurations:

    <Tabs>
      <Tab title="Environment Variables">
        | Variable                    | Description                                                                                    | Required               | Example                       |
        | --------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------- | ----------------------------- |
        | `CYBORGDB_API_KEY`          | Core license key. Free tier (1M items/index) when unset                                        | ❌                      | `cyborg_abc123...`            |
        | `CYBORGDB_SERVICE_ROOT_KEY` | Service auth root (an operator-chosen secret). Auth disabled (all requests allowed) when unset | ❌                      | `a-long-random-secret`        |
        | `CYBORGDB_DB_TYPE`          | Storage backend (`memory`, `disk`, `s3`)                                                       | ❌ (defaults to `disk`) | `s3`                          |
        | `CYBORGDB_DISK_PATH`        | Data directory for `disk` storage                                                              | ❌                      | `/var/lib/cyborgdb`           |
        | `CYBORGDB_S3_BUCKET`        | Bucket name for `s3` storage                                                                   | Required for S3        | `my-bucket`                   |
        | `CYBORGDB_S3_REGION`        | Region for `s3` storage                                                                        | ❌                      | `us-east-1`                   |
        | `PORT`                      | Service port                                                                                   | ❌                      | `8000`                        |
        | `SSL_CERT_PATH`             | Path to SSL certificate file                                                                   | ❌                      | `/etc/ssl/certs/server.crt`   |
        | `SSL_KEY_PATH`              | Path to SSL private key file                                                                   | ❌                      | `/etc/ssl/private/server.key` |

        <Note>None of these are required — the service starts with no configuration, using `disk` storage rooted at `~/.cyborgdb/data`, free-tier licensing, and authentication disabled. For the full list (including S3 credentials and KMS), see the [Environment Variables](../advanced/env-vars) guide.</Note>
      </Tab>

      <Tab title="Production Deployment">
        For production environments, consider using a process manager:

        ```bash theme={null}
        # Using gunicorn (install separately)
        pip install gunicorn
        gunicorn cyborgdb_service.main:app --port 8000

        # Using systemd service (Linux)
        sudo systemctl enable cyborgdb-service
        sudo systemctl start cyborgdb-service
        ```
      </Tab>

      <Tab title="HTTPS Configuration">
        For production deployments, configure HTTPS by providing SSL certificates:

        **Environment Variables:**

        ```bash theme={null}
        export SSL_CERT_PATH=/path/to/certificate.crt
        export SSL_KEY_PATH=/path/to/private.key
        ```

        **Complete Production Example:**

        ```bash theme={null}
        # Set all required environment variables including SSL
        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 SSL_CERT_PATH=/etc/ssl/certs/server.crt
        export SSL_KEY_PATH=/etc/ssl/private/server.key

        # Start service (will automatically use HTTPS)
        cyborgdb-service
        ```

        **Using .env File with SSL:**

        ```bash theme={null}
        # Create a .env file with SSL configuration
        cat > .env << EOF
        CYBORGDB_API_KEY=cyborg_your_api_key_here
        CYBORGDB_DB_TYPE=s3
        CYBORGDB_S3_BUCKET=cyborgdb-prod
        CYBORGDB_S3_REGION=us-east-1
        SSL_CERT_PATH=/path/to/certificate.crt
        SSL_KEY_PATH=/path/to/private.key
        EOF

        # Start service
        cyborgdb-service
        ```

        **Using Let's Encrypt (Production):**

        ```bash theme={null}
        # Install certbot (Ubuntu/Debian)
        sudo apt-get install certbot

        # Generate certificate for your domain
        sudo certbot certonly --standalone -d your-domain.com

        # Set environment variables to Let's Encrypt certificates
        export SSL_CERT_PATH=/etc/letsencrypt/live/your-domain.com/fullchain.pem
        export SSL_KEY_PATH=/etc/letsencrypt/live/your-domain.com/privkey.pem

        # Start service with HTTPS
        cyborgdb-service
        ```

        <Note>The server automatically switches to HTTPS when both certificate files are provided and exist. Without certificates, it starts in HTTP mode.</Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Next Steps">
    Now that your CyborgDB service is running, you can interact with it using client SDKs:

    **Install Client SDKs:**

    <CodeGroup>
      ```bash Python icon="python" theme={null}
      pip install cyborgdb
      ```

      ```bash JavaScript icon="js" theme={null}
      npm install cyborgdb
      ```

      ```bash TypeScript icon="code" theme={null}
      npm install cyborgdb
      ```

      ```bash Go icon="golang" theme={null}
      go get github.com/cyborginc/cyborgdb-go
      ```
    </CodeGroup>

    <CardGroup cols={2}>
      <Card title="REST API Reference" href="../../rest-api/introduction" icon="rectangle-terminal">
        Learn how to use the REST API for direct integration
      </Card>

      <Card title="Python SDK Reference" href="../../python-sdk/introduction" icon="python">
        Learn how to use the Python SDK for direct integration
      </Card>

      <Card title="JS/TS SDK Reference" href="../../js-ts-sdk/introduction" icon="js">
        Learn how to use the JavaScript/TypeScript SDK for direct integration
      </Card>

      <Card title="Go SDK Reference" href="../../go-sdk/introduction" icon="golang">
        Learn how to use the Go SDK for direct integration
      </Card>
    </CardGroup>
  </Step>
</Steps>

<Accordion title="Comparison with Docker Service">
  | Aspect                    | Python Service                      | Docker Service               |
  | ------------------------- | ----------------------------------- | ---------------------------- |
  | **Installation**          | `pip install`                       | `docker run`                 |
  | **Dependencies**          | Managed by pip/conda                | Bundled in container         |
  | **Resource Usage**        | Lower overhead                      | Higher overhead              |
  | **Environment Isolation** | Python virtualenv                   | Container isolation          |
  | **Deployment Complexity** | Simple Python deployment            | Container orchestration      |
  | **Configuration**         | Environment variables/files         | Environment variables        |
  | **Best For**              | Development, Python-heavy workflows | Production, cloud deployment |

  <Tip>Both approaches provide identical CyborgDB functionality. Choose based on your deployment preferences and infrastructure requirements.</Tip>
</Accordion>