DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Set Up and Troubleshoot DeepTutor with Your Agent
Handbook · Development · Modules · Storage
This guide is for an external agent installing, configuring, and verifying DeepTutor for a user, or investigating problems in an existing installation. For an existing problem, start with Troubleshooting rather than repeating installation. Read SKILL.md for the CLI overview. You need terminal and file access; this flow does not require MCP or an agent-specific plugin.
1. Establish the target
Ask only for missing information and continue independent preparation while waiting:
- Installation folder and any existing DeepTutor checkout.
- Full Web app or CLI-only; default to the full app for the README setup prompt.
- Target version or branch. This guide describes current
dev, including the 1.7.0 modular layout; use matching documentation for an older stable release. - LLM provider, exact model ID, and any custom/local endpoint.
- Credential source: an existing environment variable, a private local file the user identifies, or provider login. Do not ask for keys in chat.
- Whether knowledge bases/RAG are needed now; these also require embedding. Search is optional.
Reuse suitable checkouts/environments and preserve local edits and settings.
Use the user's existing DEEPTUTOR_HOME, or choose a runtime home explicitly.
It owns data/; it is not the data/ directory itself or the Content Workspace
used for learning materials.
2. Clone and install
For a new full-app installation of current dev (macOS/Linux example):
git clone --branch dev https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
cd web
npm ci --legacy-peer-deps
cd ..
Use Python 3.11–3.14 and Node.js 22 LTS for this flow. Check the actual
interpreter before creating the environment; python3 may be older. On
Windows, use a supported py -3.X and .venv\Scripts\Activate.ps1. If shell
state does not persist between tool calls, invoke the environment's Python
and deeptutor by absolute path and pass environment variables to each process.
For CLI use from source, keep the Python installation above and skip Node/npm.
A source tree exposes all checked-in modules, so it still needs their Python
dependencies. In the 1.7.0 package layout, deeptutor provides the minimal CLI;
deeptutor-cli is a compatibility alias for the same core. Add feature modules
as needed; this is not the layout of the published 1.6.15 packages.
The 1.7.0 package layout uses python -m pip install "deeptutor[full]"
for the complete Web app. Bare deeptutor contains core chat, CLI and SDK;
it does not contain the server or Web assets. For development builds,
use the source flow above or the local wheels described in
Modules.
When upgrading from 1.6.15, stop DeepTutor, back up the existing runtime home,
and keep using the same DEEPTUTOR_HOME. To install 1.7.0, run
python -m pip install --upgrade "deeptutor[full]==1.7.0", then
python -m pip check and deeptutor module list before restarting.
If the legacy deeptutor-cli package is installed, uninstall it before
installing the new packages: python -m pip uninstall deeptutor-cli. Its old
wheel owns shared Python files, and a one-command upgrade can remove the newly
installed core. This does not remove runtime-home data. You can then add
deeptutor-cli==1.7.0 to the installation command for the new metadata-only
compatibility alias. For CLI-only migration, install deeptutor-cli==1.7.0
after removing the old CLI, and add any feature modules you need.
In 1.7.0, upgrading bare deeptutor selects only core; use [full] to retain
the full-app feature set. Do not reset settings or change the runtime-home
directory during this upgrade. For an existing checkout, inspect its branch,
commit and local edits before updating; do not silently switch branches or
replace the environment to match this example.
3. Initialize without prompts
Keep the same runtime home for initialization, configuration, diagnostics, and startup. This example uses the checkout root; use the existing home instead when the user has one:
export DEEPTUTOR_HOME="$PWD"
deeptutor init --non-interactive
deeptutor config providers
init --non-interactive creates missing defaults without selecting a model or
contacting a provider and preserves saved settings. --cli is also accepted;
no wizard runs in either mode. Initialization alone does not establish model
readiness.
config providers prints supported LLM, embedding, and search providers with
default endpoints and LLM API formats as JSON. Use its provider IDs. init,
config apply, and config show also accept --home PATH; for other commands
use DEEPTUTOR_HOME consistently.
4. Apply configuration
Write a UTF-8 JSON file such as setup.json, replacing the model placeholder
with the user's choice:
{
"llm": {
"provider": "openai",
"model": "YOUR_MODEL_ID",
"api_key_env": "DEEPTUTOR_SETUP_LLM_KEY"
},
"system": {
"backend_port": 8001,
"frontend_port": 3782
}
}
The variable named by api_key_env must exist in the CLI process's environment.
Read it from the user's authorized source without echoing it. The JSON contains
a variable name, not a literal key. Resolved keys are saved in DeepTutor's
private settings for later launches. Project-root .env files are not loaded
automatically.
deeptutor config apply setup.json --check
deeptutor config apply setup.json
deeptutor config show
--check validates input, providers, named credentials, endpoints, and port
conflicts without writing settings or contacting providers. Both modes
emit JSON; invalid input exits with code 2. Application selects a dedicated
Agent Setup profile for each supplied service. Repeating it updates those
same profiles; other profiles and omitted services/settings are preserved.
Supply complete profiles, including credential references, each time. Port
changes take effect on restart.
| Section | Required fields | Optional fields |
|---|---|---|
llm |
provider, model |
base_url, api_key_env, api_version, api_format |
embedding |
provider, model |
base_url, api_key_env, api_version, positive integer dimension |
search |
provider |
base_url, api_key_env |
system |
At least one port | backend_port, frontend_port (integers 1–65535, distinct) |
Remote key-authenticated LLM/embedding providers require api_key_env; local,
OAuth, and custom endpoints may omit it. Search requirements come from
config providers. Providers without default endpoints require base_url.
LLM API formats are auto, openai_chat, openai_responses, and anthropic,
subject to the provider's supported list. Unknown fields, literal api_key
fields, and credentials in URLs are rejected. Advanced settings and other
service types remain available in Web Settings.
For knowledge bases/RAG, also configure an accessible embedding model. For example:
{
"embedding": {
"provider": "openai",
"model": "text-embedding-3-small",
"api_key_env": "DEEPTUTOR_SETUP_EMBEDDING_KEY",
"dimension": 1536
},
"search": { "provider": "duckduckgo" }
}
Embedding base_url is the full endpoint, such as
https://api.openai.com/v1/embeddings; the catalog normalizes it as the Web UI
does. Changing an existing KB's embedding model/dimensions requires planning
a rebuild. Omit search when unnecessary, or choose none to disable it.
DuckDuckGo needs no key; availability depends on the user's network.
For local Ollama, use {"llm":{"provider":"ollama","model":"YOUR_LOCAL_MODEL"}}
and verify that Ollama is running and the model is available.
For OAuth, apply the provider ID/model from config providers, then use its
existing login command in the same runtime home. The user completes any login
interaction:
deeptutor provider login openai-codex
# Other supported flows: github-copilot, codebuddy
OpenAI Codex uses DeepTutor's own OAuth credentials; the external agent's login is not automatically reused. Login does not select a model.
5. Verify and start
python -m pip check
deeptutor module list
deeptutor doctor --format json
deeptutor doctor --online --format json
pip check checks dependency consistency. Inspect module list for the modules
needed by the user: installed, enabled, and ready are separate states. The Web
app needs server and web; RAG needs knowledge and parsing; optional capabilities
need their owning modules. Core-only intentionally omits these modules. Source
checkouts use module enable/disable; wheel installs also support
module install/uninstall. Stop DeepTutor before changes, and use
--wheelhouse /path/to/wheels for unpublished modules. See Modules.
doctor checks local readiness; doctor --online makes a small real model request
and may incur provider usage. Inspect exit status and required failures. Fix
actionable failures and rerun affected checks. Saved settings alone are not
proof of readiness. The LLM probe does not verify optional embedding: when RAG
is requested, also test its connection in Settings and ingest/search a small
user-approved document.
For the full app:
deeptutor start --detach --no-browser
Read the actual launcher URLs, verify backend /health/ready, and confirm the
frontend responds. Defaults are backend http://127.0.0.1:8001 and frontend
http://127.0.0.1:3782; use the reported ports if different. Inspect launcher
logs on failure. Choose free ports through config apply instead of stopping
unrelated processes. For CLI-only, skip Web startup and verify turn execution:
deeptutor run chat "Reply with a short greeting." --format json
This also uses the configured model. Check for a successful response and turn completion, not merely a zero exit code or the first streamed event.
Finish with the checkout/environment, runtime home, provider/model without
credentials, passed checks, Web URL or CLI invocation, and any remaining user
action. Include deeptutor stop with the same home for a detached app. If
credentials or network access prevent verification, state the exact unfinished
step instead of declaring setup complete.
6. Troubleshooting
Use the following approach to investigate the user's symptom. Choose checks based on evidence; there is no need to run every command for every problem.
Identify the running instance and reproduce the symptom. Establish the installation method, installed version or source commit, active Python environment, runtime home, and actual service URLs. For Docker, distinguish container paths/ports from host paths/ports. Ask for the failing action, expected result, approximate time, and relevant recent changes. Confirm that your CLI checks target the same instance, account, and workspace as the user; a healthy second installation tells you little about the failure.
Collect the smallest useful evidence. Use
config showanddoctorfor configuration/readiness,doctor --onlinefor a real LLM request, ordoctor runtimefor turn coordination, session storage, and migration preflight. Add--format jsonto either doctor mode. Inspect individual checks: top-levelok: truecan coexist with optional failures such as RAG. A passing LLM probe does not prove that embedding, search, tools, or the browser's connection work.Follow the failing operation across its boundaries. Start from the visible symptom and determine how far the operation got: browser → API → turn/capability → provider, tool, or storage. Inspect browser console and network errors for UI problems, and correlate server logs by time and
request_id,session_id, orturn_idwhen present. For detached launches, check<runtime-home>/data/user/runtime/launcher.log; application logs normally live indata/user/logs/deeptutor.jsonl, subject to logging settings. Container deployments may also require container output. Read a narrow relevant excerpt and remove credentials and private content before sharing.Test one hypothesis at a time. Reduce the failing action to a small reproduction and compare a working path with the failing one. For example, a successful CLI turn with a failing Web turn directs attention toward the browser/API path, provided both use equivalent settings and context. Use
--help,plugin info, and the checked-out code to continue investigating. The rootAGENTS.mdmaps the architecture; useful starting points includedeeptutor_cli/,deeptutor/api/,deeptutor/runtime/,deeptutor/capabilities/,deeptutor/services/, andweb/. Match source to the installed version before drawing conclusions.Make a focused fix and verify the original action. Preserve existing data and configuration; avoid blanket reinstalls, resets, or KB rebuilds as exploratory steps. Rerun the user's failing operation after the change, not only a general health check. Report observations separately from hypotheses. If unresolved, provide a concise handoff: environment/version, reproduction, expected versus actual behavior, relevant redacted errors, checks already tried, and the next useful investigation.