Skip to main content
This guide walks you from a fresh checkout to a running DeepTutor instance with a populated knowledge base. Docker is the recommended path — no Python or Node.js setup required.

​
Prerequisites

​
Step-by-step setup

1

Clone the repository

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
2

Configure environment variables

Copy the example environment file and open it in your editor:
cp .env.example .env
At minimum, fill in the six required fields:
# LLM settings
LLM_BINDING=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=sk-...
LLM_HOST=https://api.openai.com/v1

# Embedding settings
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_API_KEY=sk-...
EMBEDDING_HOST=https://api.openai.com/v1
EMBEDDING_DIMENSION=1536
LLM_BINDING and EMBEDDING_BINDING control the provider. Supported values include openai, azure_openai, anthropic, deepseek, ollama, and others. See Configuration for a full list.
The EMBEDDING_DIMENSION must match your model’s actual output dimension. For text-embedding-3-small use 1536; for text-embedding-3-large use 3072.
3

Start DeepTutor

docker compose up
The first build takes roughly 10–15 minutes. Subsequent starts are fast because Docker caches the image layers.To run in the background:
docker compose up -d
To rebuild after pulling new code:
docker compose build --no-cache && docker compose up
4

Verify the services are running

Once startup is complete, two services are available:
ServiceURLDescription
Frontendhttp://localhost:3782Main web interface
Backend API docshttp://localhost:8001/docsInteractive Swagger UI
Open http://localhost:3782 in your browser. You should see the DeepTutor dashboard.
If you are accessing DeepTutor from another device on your network (or deploying to a remote server), you must set NEXT_PUBLIC_API_BASE in your .env file to the backend’s reachable address — for example, http://192.168.1.100:8001. See Deployment for details.
5

Create your first knowledge base

A knowledge base indexes your documents so every module can search them.
  1. Go to http://localhost:3782/knowledge.
  2. Click New Knowledge Base and enter a name (e.g., my-textbook).
  3. Upload one or more PDF, TXT, or Markdown files.
  4. Watch the terminal for indexing progress — the knowledge graph and vector store are built in the background.
Want to try DeepTutor before uploading your own files? Download the demo knowledge bases (research papers or a data science textbook) from Google Drive and extract them into the data/ directory. Demo knowledge bases use text-embedding-3-large with EMBEDDING_DIMENSION=3072.
6

Run your first query

  1. Go to http://localhost:3782/solver.
  2. Select the knowledge base you just created.
  3. Type a question about your documents and click Solve.
  4. Watch the dual-loop reasoning process unfold in real time and receive a step-by-step answer with citations.
You are now running DeepTutor.

​
Common Docker commands

docker compose up -d      # Start in background
docker compose down       # Stop and remove containers
docker compose logs -f    # Stream logs
docker compose up --build # Rebuild image and start

​
Next steps

Configuration

Tune LLM parameters, enable web search, configure TTS, and adjust research presets.

Docker deployment

Cloud deployment, custom ports, HTTPS reverse proxy, and pre-built image tags.

Knowledge base

Learn how to manage, update, and query your knowledge bases.

Smart solver

Explore the dual-loop reasoning architecture and available tool integrations.

Build docs developers (and LLMs) love

Get started for freeTalk to us