Skip to main content

​
Modal Deployment

Deploy Cognee on Modal for serverless, auto-scaling knowledge graph processing with minimal infrastructure management.
Modal is a cloud platform that lets you run code remotely with automatic scaling, perfect for variable Cognee workloads.

​
Why Modal?

Serverless Scaling

Automatically scales based on workload without server management

Cost Efficient

Pay only for compute time used, ideal for batch processing

Fast Deployment

Deploy within seconds with minimal configuration

GPU Support

Access to powerful GPUs for LLM processing when needed

​
Prerequisites

1

Modal Account

Create a free account at modal.com
2

Install Modal CLI

pip install modal
modal token new
3

Environment Variables

Set up your environment variables:
# 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"

​
Quick Deployment

1

Clone Repository

git clone https://github.com/topoteretes/cognee.git
cd cognee
2

Install Dependencies

# Install with uv (recommended)
uv sync --dev --all-extras --reinstall

# Activate virtual environment
source .venv/bin/activate
3

Deploy to Modal

# Deploy the Modal ASGI app
modal deploy distributed/deploy/modal_app.py
Monitor deployment progress and logs in your Modal dashboard.
4

Monitor Deployment

Visit your Modal dashboard to monitor the deployment status and view logs.

​
Configuration Options

Default ConfigurationUses embedded databases for quick testing:
# distributed/deploy/modal_app.py configuration
GRAPH_DATABASE = "networkx"
VECTOR_DATABASE = "lancedb"
RELATIONAL_DATABASE = "sqlite"

​
Deployment Architecture

Compute Resources

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

​
Monitoring & Debugging

Modal Dashboard

Real-time MonitoringView logs, metrics, and container status in the Modal web interface.

Log Streaming

Live LogsStream logs directly to your terminal:
modal logs cognee-app

​
Video Tutorial

​
Cost Optimization

Batch Processing: Group multiple documents together to maximize container utilization and reduce cold start costs.
Database Costs: Consider using Modal’s built-in storage for development and external managed services for production.

​
Troubleshooting

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

​
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: 
# 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:
  • 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.
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 for the full set of options.

​
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 on your own machine (or any host that can serve the frontend) and point it at your Modal endpoint: 
# 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 instead.

​
Next Steps

Scale Up

Production DeploymentConfigure external databases and optimize for production workloads.

Monitor Usage

Track CostsMonitor compute usage and optimize batch sizes for cost efficiency.

Need Help?

Join our community for Modal deployment support and best practices.