DeepTutor from HKUDS is an “agent-native learning workspace” — a self-hostable application that connects tutoring, problem solving and quiz generation with research, visualisation and practice. It is Apache-2.0 licensed with an arXiv preprint (2604.26962) behind the design.
The scope is wide: modes for Chat, Quiz, Research, Visualize, Solve, Course Study, Mastery Path and Immersive Reading, with knowledge bases, notebooks, question banks and persistent memory reusable across all of them.
Two architectural choices worth noting
Most of this project is conventional — Python 3.11–3.14 with a FastAPI backend, a Next.js 16 frontend with React 19. Two decisions are not, and they are the reason to look closer.
Memory is files, not a vector store. The design uses three file-backed layers: L1 traces, L2 per-surface facts, L3 cross-surface synthesis. The documentation describes this explicitly as “not a hidden vector store.” For a tool meant to track what a learner knows over months, that is a meaningful choice — you can read, edit, back up and delete what it believes about you, which is not true of an opaque embedding index.
Retrieval is pluggable. Each knowledge base can use a different RAG engine: LlamaIndex by default, with PageIndex, GraphRAG and LightRAG among the alternatives. That is unusual, and useful if you want to compare retrieval strategies on the same material rather than accept one.
A third detail matters if you let it run code: model-generated code executes through a sandbox that prefers a runner sidecar, then Linux bwrap, then a restricted subprocess fallback — in that order. The documentation calls local subprocess sandboxing “best effort,” which is the honest description and tells you which tier you want in place.
Getting it running
The simplest route:
mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init
deeptutor startDocker avoids the toolchain entirely:
docker run --rm --name deeptutor \
-p 127.0.0.1:3782:3782 \
-v deeptutor-data:/app/data \
ghcr.io/hkuds/deeptutor:latestThere is a from-source path and a CLI-only install (deeptutor chat) for people who want the tutor in a terminal.
Requirements are Python 3.11–3.14 and, for the PyPI install, “a Node.js 20+ runtime on PATH” — the source guide recommends Node 22 LTS. You supply your own LLM provider by saving a base URL and API key in Settings → Providers; an embedding provider is only needed for knowledge-base features, and web search is optional. FFmpeg, MinerU and LaTeX are optional extras for speech, structured parsing and maths animation.
The rough edges are documented
This is a fast-moving project and says so. The screenshots in the docs are older-release references while “a versioned refresh is in progress.” Codex OAuth compatibility is “experimental: the upstream interface may change.” MiMo speech supports presets only — “voice design and voice cloning require separate models and are not supported.” The Grok CLI connector handles text and CLI tools but not image forwarding or importing past conversations. Knowledge-base evaluation (deeptutor kb eval) excludes PageIndex because it returns no ranked chunks, and does not assess semantic equivalence. Native LightRAG indexes without a recorded embedding identity need a rebuild.
None of those are dealbreakers, but together they describe the state accurately: a broad, actively developed system where several integrations are ahead of their documentation.
Who should run it
Someone self-hosting a learning environment who wants the persistence layer to be inspectable and the retrieval strategy to be their choice. For a student or a tutor willing to supply an API key, it offers considerably more than a chat window — the question-bank and mastery-path machinery is the part a plain chat cannot replace.
Start with the Docker image and one knowledge base before wiring in the optional parsers. And if you intend to use code execution, check which sandbox tier you actually get on your host rather than assuming the best one.
