How to Run DeepTutor Locally with Ollama for Private AI Tutoring
Set up DeepTutor with Ollama for a private, self-hosted AI tutor with quiz, solve, research, and visualize modes. No cloud required.

What is DeepTutor and why run it locally?
DeepTutor is an open source learning workspace built by HKUDS. Instead of acting as a generic chatbot, it offers purpose-built modes for studying: quiz generation, step-by-step problem solving, research, visualization, and even video lessons based on YouTube content. Running it locally with Ollama means your documents, questions, and study sessions never leave your machine. That matters for anyone studying sensitive material, building a private tutoring setup, or just avoiding per-token API costs while experimenting with longer research and quiz sessions.
TL;DR
- DeepTutor is an open source tutoring workspace from HKUDS that goes beyond chat, offering dedicated quiz, solve, research, and visualize modes, each running its own workflow rather than a single generic prompt.
- Local deployment works through Docker, connecting to Ollama (or LM Studio, or cloud APIs) so you can keep documents and conversations entirely on your own hardware.
- Tool use support is required in whatever language model you connect, since DeepTutor’s workflows rely on function calling to drive its structured modes.
- A separate embedding model is needed too, used to convert documents and text into vector representations for retrieval and memory features.
- The quiz mode lets you set topic, question count, and difficulty, and can use an AI judge to double check answers alongside explanations.
- The visualize mode turns a prompt into diagrams, charts, or interactive pages, including Mermaid and SVG output, which is useful for concepts that are easier to grasp visually than in text.
- Larger local reasoning models can be slow, since more thorough chain-of-thought models take longer to respond even when the final answer is accurate.
Everyone else built a construction worker.
We built the contractor.
One file at a time.
UI, API, database, deploy.
How do you install DeepTutor?
The simplest path is Docker. With Docker already installed, pulling and running the DeepTutor image brings up two components: a backend service and a frontend interface. In a demonstrated setup, the backend ran on local port 8001 and the frontend was accessible on local port 3782. Running the container with host networking is important if you want DeepTutor to reach a local Ollama instance running on the same machine, since Ollama typically listens on localhost and isolated container networking would block that connection.
Once the container is running, the frontend loads in a browser like any other local web app, but it starts without a connected model. That connection has to be configured manually through the settings menu before any tutoring mode will work.
How do you connect DeepTutor to Ollama?
Inside DeepTutor, model connections are managed under Settings, then Providers. Clicking “Add Provider” reveals a list of supported backends: language models, embedding models, voice, search, and custom API endpoints for setups running vLLM or similar inference servers. For a local Ollama setup, select Ollama as the provider. It supports both language and embedding models through the same provider entry.
The provider URL points to your local Ollama server, no API key required. After entering the URL, selecting both “language” and “embedding” service types, and testing the connection, DeepTutor should report available models and confirm the connection works.
From there, you add the specific models separately. Under language models, “Add Model” with the Ollama provider pulls a list of models currently available in your local Ollama install. The same process applies to embedding models. Each model can be tested individually inside the settings panel before you start using it, which is a useful sanity check before diving into a quiz or research session.
What models does DeepTutor need to function?
Two things matter here. First, DeepTutor’s modes rely on tool use (function calling), since quiz generation, step-by-step solving, and research workflows aren’t just raw text completions, they’re structured processes the model needs to follow. Any language model connected to DeepTutor needs to support tool calling for these modes to work correctly. A Qwen 27-billion-parameter model (referred to in testing as “Qwen 3.8 27B”) was used successfully, since it supports tool use.
Second, DeepTutor needs an embedding model to convert text and uploaded documents into numerical vector representations. This powers retrieval, memory, and document-based question answering. Nomic Embed was used for this role in testing. Without an embedding model configured, document upload and memory features won’t function properly even if the language model is connected.
Running locally is hardware-dependent. A single GPU with substantial VRAM (48GB in the demonstrated setup) comfortably handled a 27-billion-parameter model alongside an embedding model. Smaller GPUs would need smaller quantized models or a provider setup that offloads inference elsewhere.
What can you actually do with DeepTutor’s modes?
Build an onboarding app for 4,000 new hires.
Build ↵Chat mode behaves like a standard chatbot connected to your local model, useful for quick questions but not the main point of the tool. The other modes are where DeepTutor differentiates itself:
Quiz mode generates custom quizzes based on a topic, question count, and difficulty level you specify. It checks answers against each question, provides explanations, and can use a separate AI judge pass to verify correctness before moving on.
Solve mode is built for multi-step reasoning problems rather than single-shot answers. It works through logic puzzles or multi-part problems step by step, similar to how a tutor would walk through a solution rather than just stating the result.
Research mode generates a structured research outline on a topic, with options for different output styles such as study notes, a report, a comparison, or a learning path. Deeper research settings consume more tokens and more time, giving you a tradeoff between thoroughness and speed.
Visualize mode converts a prompt into a diagram, chart, or interactive visual rather than a text answer. Output formats include Mermaid diagrams, SVG, and auto-selected rendering, which is useful for visually explaining processes like the phases of the moon or any sequential concept.
Beyond these four, DeepTutor also includes a reading mode for YouTube videos, a voice mode, and a task board with calendar features aimed at turning it into a more complete study tool rather than a single-purpose chatbot.
Is DeepTutor worth setting up locally?
For anyone already comfortable running local models through Ollama, DeepTutor adds meaningful structure on top of a raw chatbot. The same results could technically be achieved by writing custom prompts or workflows against a local model directly, but DeepTutor packages quiz generation, step-by-step solving, structured research, and visualization as ready-made workflows rather than something you have to build yourself.
The tradeoff is setup complexity and model requirements. You need a tool-use-capable language model, a working embedding model, Docker, and some comfort configuring provider settings that aren’t fully polished yet. Response times with larger reasoning models can also be slow, since more thorough models take longer to think through structured workflows compared to a quick direct answer.
For privacy-conscious learners, students working with sensitive documents, or anyone wanting a self-hosted tutor without per-query API costs, the setup overhead is a reasonable tradeoff for keeping everything local.
Frequently Asked Questions
Does DeepTutor require an internet connection to run?
No, once installed via Docker and connected to a local Ollama instance, DeepTutor can run fully offline, since both the language model and embedding model operate locally.
Can DeepTutor work with models other than Qwen?
Yes, any language model that supports tool use should work, since DeepTutor’s workflows depend on function calling. It also supports LM Studio and cloud-based API models in addition to Ollama.
Why does DeepTutor need two models instead of one?
It needs a language model for reasoning and generating responses, and a separate embedding model to convert documents and text into vector representations used for retrieval and memory.
What hardware do you need to run DeepTutor locally?
Build an enterprise app with Dmitry Shapiro. Leave certified.
Requirements depend on the model size you choose. A 27-billion-parameter model paired with an embedding model ran on a single GPU with 48GB of VRAM, though smaller quantized models could work on less powerful hardware.
What’s the difference between solve mode and quiz mode?
Quiz mode generates test questions with answer checking and explanations, while solve mode works through a single complex, multi-step problem the way a tutor would walk through a solution.
