> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Modal Deployment

> Deploy Cognee on Modal for serverless, auto-scaling knowledge graph processing

# Modal Deployment

Deploy Cognee on Modal for serverless, auto-scaling knowledge graph processing with minimal infrastructure management.

<Info>
  Modal is a cloud platform that lets you run code remotely with automatic scaling, perfect for variable Cognee workloads.
</Info>

## Why Modal?

<CardGroup cols={2}>
  <Card title="Serverless Scaling" icon="trending-up">
    Automatically scales based on workload without server management
  </Card>

  <Card title="Cost Efficient" icon="dollar-sign">
    Pay only for compute time used, ideal for batch processing
  </Card>

  <Card title="Fast Deployment" icon="rocket">
    Deploy within seconds with minimal configuration
  </Card>

  <Card title="GPU Support" icon="cpu">
    Access to powerful GPUs for LLM processing when needed
  </Card>
</CardGroup>

## Prerequisites

<Steps>
  <Step title="Modal Account">
    Create a free account at [modal.com](https://modal.com/)
  </Step>

  <Step title="Install Modal CLI">
    ```bash theme={null}
    pip install modal
    modal token new
    ```
  </Step>

  <Step title="Environment Variables">
    Set up your environment variables:

    ```bash theme={null}
    # Required
    export OPENAI_API_KEY="your-openai-api-key"

    # Optional - for external databases
    export POSTGRES_URL="postgresql://user:pass@host:5432/db"
    export NEO4J_URL="bolt://user:pass@host:7687"
    export QDRANT_URL="http://host:6333"
    ```
  </Step>
</Steps>

## Quick Deployment

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/topoteretes/cognee.git
    cd cognee
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    # Install with uv (recommended)
    uv sync --dev --all-extras --reinstall

    # Activate virtual environment
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Deploy to Modal">
    ```bash theme={null}
    # Deploy the Modal ASGI app
    modal deploy distributed/deploy/modal_app.py
    ```

    <Note>
      Monitor deployment progress and logs in your Modal dashboard.
    </Note>
  </Step>

  <Step title="Monitor Deployment">
    Visit your [Modal dashboard](https://modal.com/apps) to monitor the deployment status and view logs.
  </Step>
</Steps>

## Configuration Options

<Tabs>
  <Tab title="Basic Setup">
    **Default Configuration**

    Uses embedded databases for quick testing:

    ```python theme={null}
    # distributed/deploy/modal_app.py configuration
    GRAPH_DATABASE = "networkx"
    VECTOR_DATABASE = "lancedb"
    RELATIONAL_DATABASE = "sqlite"
    ```
  </Tab>

  <Tab title="Production Setup">
    **External Databases**

    Connect to managed database services:

    ```python theme={null}
    # Production configuration
    POSTGRES_URL = "postgresql://user:pass@rds-host:5432/cognee"
    NEO4J_URL = "bolt://user:pass@aura-host:7687"
    QDRANT_URL = "https://your-cluster.qdrant.io"
    ```
  </Tab>

  <Tab title="Hybrid Setup">
    **Mixed Storage**

    Combine local and cloud storage:

    ```python theme={null}
    # Hybrid configuration
    VECTOR_DATABASE = "s3://your-bucket/vectors/"
    GRAPH_DATABASE = "neo4j://managed-instance"
    RELATIONAL_DATABASE = "postgresql://rds-instance"
    ```
  </Tab>
</Tabs>

## Deployment Architecture

<AccordionGroup>
  <Accordion title="Compute Resources" defaultOpen>
    Modal automatically provisions compute resources based on your workload:

    * **CPU**: 2-16 cores per container
    * **Memory**: 4-64 GB RAM per container
    * **GPU**: Optional NVIDIA GPUs for LLM processing
    * **Storage**: Ephemeral storage per container
  </Accordion>

  <Accordion title="Auto-scaling">
    Modal scales your deployment automatically:

    * **Cold Start**: \~2-5 seconds to spin up new containers
    * **Concurrent Processing**: Multiple containers for parallel workloads
    * **Auto-shutdown**: Containers shut down when idle to save costs
  </Accordion>

  <Accordion title="Data Persistence">
    Configure persistent storage for your data:

    * **Volumes**: Modal volumes for persistent file storage
    * **External DBs**: Connect to managed database services
    * **S3 Integration**: Direct S3 access for large datasets
  </Accordion>
</AccordionGroup>

## Monitoring & Debugging

<CardGroup cols={2}>
  <Card title="Modal Dashboard" icon="monitor">
    **Real-time Monitoring**

    View logs, metrics, and container status in the Modal web interface.
  </Card>

  <Card title="Log Streaming" icon="terminal">
    **Live Logs**

    Stream logs directly to your terminal:

    ```bash theme={null}
    modal logs cognee-app
    ```
  </Card>
</CardGroup>

## Video Tutorial

<iframe width="100%" height="400" src="https://www.youtube.com/embed/86SWVdI5K0Y" title="Cognee Modal Deployment Tutorial" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Cost Optimization

<Tip>
  **Batch Processing**: Group multiple documents together to maximize container utilization and reduce cold start costs.
</Tip>

<Note>
  **Database Costs**: Consider using Modal's built-in storage for development and external managed services for production.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues">
    **Container Timeout**

    * Increase timeout limits in `distributed/deploy/modal_app.py`
    * Break large datasets into smaller batches

    **Memory Errors**

    * Increase container memory allocation
    * Use streaming processing for large files
  </Accordion>

  <Accordion title="Environment Variables">
    **Missing API Keys**

    * Ensure all required environment variables are set
    * Use Modal secrets for sensitive data

    **Database Connections**

    * Verify database URLs and credentials
    * Check network connectivity from Modal containers
  </Accordion>
</AccordionGroup>

## Authentication & API Keys

Secrets on Modal are injected as environment variables through a Modal secret group rather than committed to the image. The `serve` function in `distributed/deploy/modal_app.py` reads from a secret group named `cognee-secrets`:

```bash theme={null}
# Create the secret group with your credentials
modal secret create cognee-secrets \
  LLM_API_KEY=sk-xxx \
  LLM_MODEL=openai/gpt-4o-mini
```

Add any other configuration values (database URLs, `ENABLE_BACKEND_ACCESS_CONTROL`, etc.) as additional `KEY=value` pairs in the same command.

The deployed FastAPI server uses the same authentication model as any [self-hosted REST API server](/guides/deploy-rest-api-server#authentication):

* Authentication is on whenever `ENABLE_BACKEND_ACCESS_CONTROL=true` (the default). Register with `POST /api/v1/auth/register`, log in via `POST /api/v1/auth/login`, and send the returned token as an `Authorization: Bearer <token>` header.
* For long-lived SDK or REST clients, create an API key with `POST /api/v1/auth/api-keys` after logging in, then pass it as the `X-Api-Key` header or as `api_key` when calling `cognee.serve(...)`.
* For a single-user deployment without auth, add `ENABLE_BACKEND_ACCESS_CONTROL=false` to the secret group. Setting `REQUIRE_AUTHENTICATION=false` alone is **not** sufficient while multi-tenant mode is on.

<Note>
  Modal endpoints are public by default. Keep `ENABLE_BACKEND_ACCESS_CONTROL=true` for anything beyond local testing, and set `CORS_ALLOWED_ORIGINS` to your frontend's domain rather than `*`. See [Setup Configuration → Security](/setup-configuration/security) for the full set of options.
</Note>

## Hosting the UI

The Modal deployment hosts the **backend API only** — `modal_app.py` serves the Cognee FastAPI app as an ASGI app and does not bundle the Next.js frontend. There is no built-in UI deployment for Modal.

To use the UI with a Modal-hosted backend, run the [local UI](/cognee-cloud/local-ui) on your own machine (or any host that can serve the frontend) and point it at your Modal endpoint:

```bash theme={null}
# Frontend → Modal backend
export NEXT_PUBLIC_LOCAL_API_URL="https://<your-org>--cognee-api-serve.modal.run"
```

Because the browser then calls the Modal endpoint from a different origin, add that frontend origin to the backend's CORS policy in the `cognee-secrets` group (for example `CORS_ALLOWED_ORIGINS=http://localhost:3000`). For a fully managed UI without self-hosting, use [Cognee Cloud](/cognee-cloud/overview) instead.

## Next Steps

<CardGroup cols={2}>
  <Card title="Scale Up" icon="trending-up">
    **Production Deployment**

    Configure external databases and optimize for production workloads.
  </Card>

  <Card title="Monitor Usage" icon="bar-chart">
    **Track Costs**

    Monitor compute usage and optimize batch sizes for cost efficiency.
  </Card>
</CardGroup>

<Card title="Need Help?" href="https://discord.gg/m63hxKsp4p" icon="discord">
  Join our community for Modal deployment support and best practices.
</Card>