SurfSense

Connect SurfSense to TensorX and get a powerful AI research agent with access to your internal knowledge sources and external data.

---

What is SurfSense?

SurfSense is an open-source AI research agent and knowledge management platform. It's an alternative to NotebookLM, Perplexity, and Glean, connecting any LLM to your internal knowledge sources and external services.

Why SurfSense + TensorX?

• 🔍 Powerful search - Hybrid semantic + full-text search across all your content
• 📁 50+ file formats - Documents, images, videos, and more
• 🔗 External integrations - Google Drive, Slack, Notion, GitHub, and more
• 🎙️ Podcast generation - Create podcasts from your research in seconds
• 👥 Team collaboration - Role-based access control for shared knowledge bases

---

Prerequisites

• Docker and Docker Compose installed
• A TensorX API key (sign up here)
• At least 4GB RAM and 20GB disk space
• PostgreSQL with pgvector extension (included in Docker setup)

---

Quick Start with Docker

1. Clone the SurfSense repository:

git clone https://github.com/MODSetter/SurfSense.git
cd SurfSense

1. Create your environment file:

cp surfsense_backend/.env.example surfsense_backend/.env

1. Edit surfsense_backend/.env and configure TensorX:

# Database (use defaults for Docker)
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/surfsense

# Authentication
AUTH_TYPE=LOCAL
SECRET_KEY=your-secure-secret-key

# Frontend URL
NEXT_FRONTEND_URL=http://localhost:3000

# Celery (Redis)
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# ETL Service (choose one)
ETL_SERVICE=DOCLING

1. Start SurfSense:

docker compose up -d

1. Access SurfSense at http://localhost:3000

---

Configuring TensorX LLM

SurfSense uses LiteLLM for LLM integration, supporting 100+ models. Configure TensorX through the SurfSense UI:

Step 1: Access LLM Settings

1. Log in to SurfSense at http://localhost:3000
2. Go to Settings → LLM Configuration

Step 2: Add TensorX as Provider

Create a new LLM configuration:

Field	Value
Provider	OpenAI Compatible
Model	openai/deepseek/deepseek-chat-v3.1
API Base	https://api.tensorx.ai/v1
API Key	Your TensorX API key

Model format: Use openai/ prefix followed by the TensorX model name. This tells LiteLLM to route requests to an OpenAI-compatible endpoint.

Step 3: Test the Connection

Click Test Connection to verify your configuration works.

---

LiteLLM Model Format

SurfSense uses LiteLLM which requires specific model naming:

openai/<tensorx-model-name>

Examples

TensorX Model	LiteLLM Format
z-ai/glm-5.1	openai/z-ai/glm-5.1
minimax/minimax-m2.5	openai/minimax/minimax-m2.5
moonshotai/kimi-k2.5	openai/moonshotai/kimi-k2.5
deepseek/deepseek-chat-v3.1	openai/deepseek/deepseek-chat-v3.1
deepseek/deepseek-r1-0528	openai/deepseek/deepseek-r1-0528
meta-llama/llama-3.3-70b-instruct	openai/meta-llama/llama-3.3-70b-instruct

---

Recommended Models

Use Case	Model	LiteLLM Format
General chat	deepseek/deepseek-chat-v3.1	openai/deepseek/deepseek-chat-v3.1
Complex reasoning	deepseek/deepseek-r1-0528	openai/deepseek/deepseek-r1-0528
Coding tasks	z-ai/glm-5.1	openai/z-ai/glm-5.1
Vision tasks	moonshotai/kimi-k2.5	openai/moonshotai/kimi-k2.5
Long context	meta-llama/llama-4-maverick	openai/meta-llama/llama-4-maverick
Fast responses	meta-llama/llama-3.3-70b-instruct	openai/meta-llama/llama-3.3-70b-instruct

---

Configuring TTS for Podcasts

SurfSense can generate podcasts from your research. Configure TensorX TTS:

Environment Variables

Add to your surfsense_backend/.env:

# Text-to-Speech
TTS_SERVICE=openai/tts-1
TTS_SERVICE_API_KEY=your-tensorx-api-key
TTS_SERVICE_API_BASE=https://api.tensorx.ai/v1

Or use TensorX's Chatterbox model:

TTS_SERVICE=openai/chatterbox-turbo
TTS_SERVICE_API_KEY=your-tensorx-api-key
TTS_SERVICE_API_BASE=https://api.tensorx.ai/v1

---

Features with TensorX

🔍 Search Spaces

Create organized knowledge bases with semantic and full-text search.

📁 File Upload

Upload 50+ file formats including:

• Documents (PDF, Word, Excel, PowerPoint)
• Images (with OCR)
• Videos and audio files

🔗 External Connectors

Connect to external services:

• Google Drive, Gmail, Calendar
• Slack, Discord
• Notion, Confluence
• GitHub, Linear, Jira
• And many more

💬 AI Chat

Chat with your knowledge base using TensorX models. Get cited answers with source references.

🎙️ Podcast Generation

Generate engaging podcasts from your research:

1. Select content from your search space
2. Click Generate Podcast
3. Download the audio file

---

Docker Compose Configuration

Full docker-compose.yml for SurfSense with TensorX:

version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: surfsense
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"

  backend:
    build: ./surfsense_backend
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/surfsense
      - SECRET_KEY=your-secure-secret-key
      - AUTH_TYPE=LOCAL
      - NEXT_FRONTEND_URL=http://localhost:3000
      - CELERY_BROKER_URL=redis://redis:6379/0
      - CELERY_RESULT_BACKEND=redis://redis:6379/0
      - ETL_SERVICE=DOCLING
      - TTS_SERVICE=openai/chatterbox-turbo
      - TTS_SERVICE_API_KEY=your-tensorx-api-key
      - TTS_SERVICE_API_BASE=https://api.tensorx.ai/v1
    ports:
      - "8000:8000"
    depends_on:
      - postgres
      - redis

  frontend:
    build: ./surfsense_web
    environment:
      - NEXT_PUBLIC_FASTAPI_BACKEND_URL=http://localhost:8000
      - NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=LOCAL
      - NEXT_PUBLIC_ETL_SERVICE=DOCLING
    ports:
      - "3000:3000"
    depends_on:
      - backend

volumes:
  postgres_data:

---

Troubleshooting

LLM Not Responding

1. Verify the model format includes openai/ prefix
2. Check API base URL: https://api.tensorx.ai/v1
3. Test your API key:

curl https://api.tensorx.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek/deepseek-chat-v3.1",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Podcast Generation Fails

1. Verify TTS environment variables are set correctly
2. Check that TTS_SERVICE_API_BASE includes /v1
3. Ensure your API key has sufficient credits

Database Connection Issues

1. Ensure PostgreSQL is running: docker ps
2. Check pgvector extension is installed
3. Verify DATABASE_URL format

Check Logs

# Backend logs
docker logs surfsense-backend-1

# All services
docker compose logs -f

---

Resources

• SurfSense Documentation
• SurfSense GitHub
• LiteLLM Providers
• TensorX Models & Pricing

---

See Also

• Audio API - Text-to-speech and speech-to-text
• API Examples - Code examples for TensorX API
• Open Notebook - Another NotebookLM alternative