> 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

Configure SurfSense to use TensorX for model requests.

***

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

***

## 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/<MODEL_ID>`         |
| 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>
```

Replace `<tensorx-model-name>` with an ID returned by `GET /v1/models`.

***

## Model selection

Call `GET /v1/models` with your TensorX API key and use one of the returned IDs. If the integration depends on a capability or token limit, query `GET /v1/model/info` before selecting the model. See [Models](/api-reference/models.md) for examples.

***

## 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 (TensorX Chatterbox)
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": "z-ai/glm-5.2",
    "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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.