How to Install DeepTutor Locally: 4 Methods from Guided Setup to Docker

To install DeepTutor locally, clone the HKUDS/DeepTutor repository, create a Python 3.11 environment, and either run the interactive python scripts/start_tour.py for automatic configuration, or manually install dependencies with pip install -e ".[server]" and npm install in the web directory.

DeepTutor is an agent-native tutoring platform built on a two-layer plugin architecture (Tools and Capabilities) that powers a FastAPI backend, a Next.js frontend, and a rich CLI. This guide walks through four distinct installation pathways based on the official source code, covering the automated Setup Tour, manual installation, Docker deployment, and CLI-only usage.

Prerequisites for Local Installation

Before installing DeepTutor, ensure your system meets these baseline requirements:

• Python 3.11 – The runtime specifically targets Python 3.11 for compatibility with the agent orchestration layer.
• Node.js – Required for the Next.js frontend located in the web/ directory.
• Git – To clone the HKUDS/DeepTutor repository.
• Docker (optional) – Only needed if you choose the containerized deployment path.

Method 1: Guided Setup Tour (Recommended)

The Setup Tour is the fastest way to get started. The scripts/start_tour.py script handles dependency installation, environment configuration, and temporary server initialization automatically.

Step 1: Clone the Repository

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

Step 2: Create a Python 3.11 Environment

conda create -n deeptutor python=3.11 && conda activate deeptutor

# Or using venv:

python -m venv .venv && source .venv/bin/activate

Step 3: Run the Interactive Installer

The installer checks for system dependencies (including Math Animator requirements) and installs Python and Node modules:

python scripts/start_tour.py

Step 4: Configure Providers via Browser

During execution, the script prompts you to:

• Select a profile (web-basic or web-rag).
• Confirm backend (default 8001) and frontend (default 3782) ports.
• Automatically open http://localhost:<frontend_port>/settings?tour=true to enter LLM, embedding, and search provider credentials.

Once you click "Complete & Launch", DeepTutor starts automatically on your specified ports.

Method 2: Manual Local Installation

For full control over the configuration process or CI/CD integration, install each component manually according to the structure defined in deeptutor/runtime/orchestrator.py and the registry files.

Install Python Dependencies

From the repository root:

pip install -e ".[server]"

This command installs the FastAPI backend, CLI tools, and optional RAG dependencies defined in requirements/server.txt.

Install Frontend Dependencies

cd web
npm install
cd ..

Configure Environment Variables

Copy the template and edit the required fields:

cp .env.example .env

Edit .env to set at minimum:

• LLM_BINDING, LLM_MODEL, LLM_API_KEY, LLM_HOST
• EMBEDDING_BINDING, EMBEDDING_MODEL, EMBEDDING_API_KEY, EMBEDDING_HOST
• SEARCH_PROVIDER and SEARCH_API_KEY (optional)

Start the Services

Run the backend and frontend in separate terminals:

# Terminal 1 - Backend (port 8001 by default)

python -m deeptutor.api.run_server

# Terminal 2 - Frontend (port 3782)

cd web && npm run dev -- -p 3782

Method 3: Docker Deployment

For a containerized installation that requires no local Python or Node installation, use the pre-built images via docker-compose.ghcr.yml.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
cp .env.example .env

# Edit .env with your API keys and port preferences

docker compose -f docker-compose.ghcr.yml up -d

The compose file mounts ./data for persistent storage of knowledge bases and user memory. To build locally instead of using the pre-built image, run docker compose up -d without the -f docker-compose.ghcr.yml flag.

Method 4: CLI-Only Installation

If you only need the terminal interface without the web UI, install the lightweight CLI package:

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
conda create -n deeptutor python=3.11 && conda activate deeptutor
pip install -e ".[cli]"

The CLI entry point in deeptutor_cli/main.py registers sub-commands for agent interaction and knowledge base management:

# Interactive REPL

deeptutor chat

# Single command execution

deeptutor run chat "Explain the Fourier transform"

# Knowledge base operations

deeptutor kb create my-kb --doc paper.pdf

How the Architecture Supports Local Deployment

DeepTutor's runtime is orchestrated by ChatOrchestrator in deeptutor/runtime/orchestrator.py, which routes requests between Tools (single-function utilities) and Capabilities (multi-step agent pipelines). These are discovered dynamically by tool_registry.py and capability_registry.py, allowing the local installation to function immediately after environment variables are configured, without additional manual registration of components.

Summary

• Setup Tour: Run python scripts/start_tour.py for an automated, browser-guided installation that handles Python 3.11 setup, dependency installation, and provider configuration.
• Manual Install: Use pip install -e ".[server]" and npm install in web/ for full control over the FastAPI backend and Next.js frontend startup process.
• Docker: Execute docker compose -f docker-compose.ghcr.yml up -d after configuring .env for a zero-dependency local deployment with persistent ./data storage.
• CLI-Only: Install with pip install -e ".[cli]" to access the terminal interface defined in deeptutor_cli/main.py without running the web server.

Frequently Asked Questions

What Python version does DeepTutor require?

DeepTutor requires Python 3.11 specifically. The agent orchestration layer and dependency stack in requirements/server.txt are tested against this version. Using older Python versions may result in compatibility errors with the async runtime used by ChatOrchestrator.

Which environment variables are mandatory to start DeepTutor?

At minimum, you must configure LLM and embedding provider variables in .env: LLM_BINDING, LLM_MODEL, LLM_API_KEY, LLM_HOST, plus EMBEDDING_BINDING, EMBEDDING_MODEL, EMBEDDING_API_KEY, and EMBEDDING_HOST. Search provider keys are optional unless using the web-rag profile that queries external search APIs.

Can I use DeepTutor without installing Node.js?

Yes. If you skip the web frontend, install only the CLI with pip install -e ".[cli]" and interact via the terminal using commands from deeptutor_cli/main.py. Alternatively, use the Docker deployment method, which bundles the Node.js frontend inside the container without requiring a local Node installation.

How do I update my local DeepTutor installation?

For manual installations, pull the latest changes with git pull and reinstall Python dependencies with pip install -e ".[server]" --upgrade. For Docker deployments, run docker compose -f docker-compose.ghcr.yml pull followed by docker compose up -d to fetch the latest pre-built images. The Setup Tour users should re-run python scripts/start_tour.py after pulling updates to ensure requirements/server.txt changes are applied.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}