> For the complete documentation index, see [llms.txt](https://docs.tensorx.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tensorx.ai/research-and-knowledge/surfsense.md).

# 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](https://github.com/MODSetter/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.

{% hint style="success" %}
**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
  {% endhint %}

***

## Prerequisites

* Docker and Docker Compose installed
* A TensorX API key ([sign up here](https://app.tensorx.ai))
* 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:

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

2. Create your environment file:

```bash
cp surfsense_backend/.env.example surfsense_backend/.env
```

3. Edit `surfsense_backend/.env` and configure TensorX:

```bash
# 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
```

4. Start SurfSense:

```bash
docker compose up -d
```

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

{% hint style="info" %}
**Model format**: Use `openai/` prefix followed by the TensorX model name. This tells LiteLLM to route requests to an OpenAI-compatible endpoint.
{% endhint %}

### 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`:

```bash
# 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:

```bash
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:

```yaml
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:

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

```bash
# Backend logs
docker logs surfsense-backend-1

# All services
docker compose logs -f
```

***

## Resources

* [SurfSense Documentation](https://www.surfsense.com/docs/)
* [SurfSense GitHub](https://github.com/MODSetter/SurfSense)
* [LiteLLM Providers](https://docs.litellm.ai/docs/providers)
* [TensorX Models & Pricing](https://tensorx.ai/models)

***

## See Also

* [Audio API](/api-reference/audio.md) - Text-to-speech and speech-to-text
* [API Examples](/api-reference/api-examples.md) - Code examples for TensorX API
* [Open Notebook](/research-and-knowledge/open-notebook.md) - Another NotebookLM alternative


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tensorx.ai/research-and-knowledge/surfsense.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.