HKUDS/DeepTutor

✨ Key Features

DeepTutor is an agent-native learning workspace that connects tutoring, problem solving, quiz generation, research, visualization, and mastery practice in one extensible system.

• One runtime for every mode — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading, and Audio Overview share one capability runtime and session context w
• Task Board — Track study tasks in To do, In progress, and Done, with notes, drag-and-drop or keyboard-accessible move buttons, and an archive you can restore from. Cards stay in the current workspace
• Connected learning context — Knowledge bases, books, Co-Writer drafts, notebooks, question banks, personas, and Memory can be reused across the workflows that support them, subject to account grants a
• Immersive video learning — add YouTube or Bilibili links to Reading for native playback, transcript search, timestamp-grounded tutoring, saved notes, and resumable progress; YouTube captions and brows
• Subagents and Partners — from Chat, consult a live agent harness (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw, or DeepSeek) or a Partner, import past conversation
• Multi-engine knowledge — versioned RAG libraries across LlamaIndex, PageIndex, GraphRAG, LightRAG, a remote LightRAG Server, a self-hosted WeKnora knowledge base, a Tencent IMA or MarginNote 4 library
• Extensible tools and skills — built-in tools, MCP servers, CLI apps, image / video / voice generation models, and installable community skills from EduHub.
• Inspectable memory — L1 traces, L2 surface summaries, and L3 synthesis make personalization visible and editable; the Memory Graph links L2 facts to L1 evidence and L3 synthesis to contributing surfac

📰 News

• 2026-05-22 🌐 Official docs site live at deeptutor.info — guides, references, and capability tours in one place.
• 2026-04-10 📄 Our paper is live on arXiv — read the preprint for the design and ideas behind DeepTutor.
• 2026-01-01 🎊 Happy New Year! Join our Discord, WeChat, or Discussions — let's shape DeepTutor together.
• 2025-12-29 🎓 DeepTutor is officially released!

Content Workspace

The Content Workspace is separate from DeepTutor's private runtime home. It is the folder agents may read, with generated files under outputs////. Custom workspaces isolate conversations, learning materials, progress, and caches in a private .deeptutor/data/ tree that file tools cannot browse. Settings, credentials, and Memory stay shared at the account level.

Without configuration, the content workspace is /data/user/workspace. Local PyPI, CLI, and source installs can choose folders in Settings → Workspaces; set the default folder with:

Capabilities inspect their selected workspace through the built-in workspace tools. The model only receives relative paths such as outputs/...; when it uses workspacepresent, the UI renders an authenticated, openable snapshot. The same exact relative path also works in a normal Markdown link or image. Changing the source file later does not change an already presented snapshot.

Learning Space manages the resource library. In Settings → Workspaces, assign Skills, MCP services and knowledge bases to each workspace, or retain its existing access rules. Existing workspaces keep their current access until a selection is saved. Assignments reference the original resources without copying credentials or knowledge indexes; workspace-specific skills can override shared versions. See workspace resource assignments.

• ghcr.io/hkuds/deeptutor:latest — latest stable release
• ghcr.io/hkuds/deeptutor: — exact release without the leading v (for example :1.6.3); pre-releases receive only their version tag
• Different host ports: change the left side of each -p host:container mapping (e.g. -p 127.0.0.1:8088:3782). If you change container-side ports in /app/data/user/settings/system.json, restart and updat
• Detached: add -d, then docker logs -f deeptutor to follow, docker stop deeptutor to stop, docker rm deeptutor before reusing the name. The deeptutor-data volume keeps private runtime data and the defa
• Ollama LLM: http://host.docker.internal:11434/v1
• Ollama embedding: http://host.docker.internal:11434/api/embed
• LM Studio: http://host.docker.internal:1234/v1
• llama.cpp: http://host.docker.internal:8080/v1
• Lemonade: http://host.docker.internal:13305/api/v1
• Runner sidecar: DEEPTUTORSANDBOXRUNNERURL routes execution to the
• hardened, least-privileged service from Dockerfile.runner.
• Linux bubblewrap: when available, bwrap isolates the process and files.
• Restricted subprocess fallback: local and single-container installs use
• this only when allowed; under Docker the container remains another boundary.

⌨️ DeepTutor CLI — Agent-Native Interface

One deeptutor binary, two ways in: an interactive REPL for people who live in the terminal, and structured JSON for other agents that drive DeepTutor as a tool. Same capabilities, tools, and knowledge bases either way.

deeptutor chat opens an interactive REPL and selects a mode with --capability; deeptutor run "" takes that capability as its first positional argument and exits after one turn. Both accept --tool, --kb, --config, and --workspace to select a registered workspace.

Core workspace management is here too — knowledge bases (kb), sessions (session), partners (partner), skills (skill), notebooks, memory, and config; course and session organization remain in the Web app. Full list below.

DeepTutor is built to be operated by another agent. Add --format json to any run and each turn streams NDJSON — one event per line (content, toolcall, toolresult, done, …), every line tagged with its sessionid. Runs are headless-safe: an askuser pause with no TTY auto-resolves with an empty reply instead of hanging.

• deeptutor init [--non-interactive] [--home PATH] — Run the setup wizard, or create missing defaults without prompts
• deeptutor doctor [--online] — Check whether the runtime is ready to start a session; --online also probes the configured model provider, --format json prints the report
• deeptutor start [--home PATH] [--dev] [--detach] [--no-browser] — Launch backend + frontend together; optionally detach or suppress browser opening
• deeptutor stop [--home PATH] — Stop a launcher started with --detach
• deeptutor serve [--port PORT] — Start only the FastAPI backend
• deeptutor workspace show/set/reset — Inspect, select, or restore the per-user Content Workspace
• deeptutor run — Run a single capability turn (chat, askquestions, deepsolve, deepquestion, deepresearch, visualize, mathanimator, masterypath, immersivereading, coursestudy, audiooverview); add --form
• deeptutor chat — Interactive REPL with capability, tool, KB, notebook, and history controls
• deeptutor partner list/create/start/stop — Manage IM-connected partners
• deeptutor kb list/info/create/connect-kiwix/add/search/eval/eval-diff/set-default/delete/list-sources/sync — Manage knowledge bases, connect Kiwix archives, score and compare retrieval runs, and synch
• deeptutor skill search/install/list/remove/login/logout/publish/update — Manage skills, install from hubs, and publish your own (eduhub: by default, see Ecosystem)
• deeptutor memory show/clear — Inspect L2/L3 memory docs or clear L1/all memory
• deeptutor session list/show/open/rename/delete — Manage shared sessions
• deeptutor notebook list/create/show/add-md/replace-md/remove-record — Manage notebooks from Markdown files