DeepTutor Configuration Files: A Complete Guide to Setup and Customization

DeepTutor relies on a hierarchical system of YAML and ENV files—located in config/, data/user/settings/, and the root directory—to manage everything from API keys and server ports to LLM temperature settings and UI preferences.

The HKUDS/DeepTutor repository implements a flexible configuration architecture that separates global defaults, agent-level parameters, and per-user overrides. Understanding where these DeepTutor configuration files reside and how they interact is essential for customizing the platform to your specific deployment needs.

Environment Variables: The .env Templates

The foundation of DeepTutor's configuration starts with environment variables defined in .env files.

The repository provides .env.example (and .env.example_CN for Chinese deployments) as templates for the runtime .env file. These templates specify critical runtime parameters including:

• API keys for LLM and embedding providers
• Database connection paths
• UI endpoint URLs

Copy .env.example to .env and populate your secrets before starting the platform.

Global Configuration: config/main.yaml

The config/main.yaml file serves as the global configuration store for DeepTutor. This file is generated at runtime on first launch if it does not already exist, so it does not ship with the repository.

According to the pre-configuration documentation, this YAML defines:

server:
  backend_port: 8001
  ui_port: 3000
logging:
  level: INFO
  log_dir: logs/
providers:
  llm:
    name: openai
    api_key: ${OPENAI_API_KEY}
  embedding:
    name: openai
    api_key: ${OPENAI_API_KEY}

The file controls server ports, logging levels, provider selections (LLM, embedding, RAG), and default UI language settings.

Agent Defaults: config/agents.yaml

DeepTutor maintains unified agent-level defaults in config/agents.yaml, also generated at runtime. This file establishes baseline parameters that all capabilities inherit unless explicitly overridden.

Key parameters include:

• temperature: Default sampling temperature for LLM responses
• max_tokens: Maximum token limits for generated content
• Tool-specific timeouts for external integrations

These values provide the fallback configuration for the entire agent system.

Per-User Configuration Overrides

DeepTutor supports granular, user-specific settings stored in data/user/settings/. These runtime files allow individual customization without modifying global defaults.

data/user/settings/main.yaml

This file captures per-user preferences such as system language and UI customizations. The platform updates this file automatically when users execute CLI configuration commands.

data/user/settings/agents.yaml

For agent-specific customizations, users can override global defaults in this file. For example, setting a lower max_tokens limit for a specific user account.

Managing Configuration via CLI

DeepTutor provides a dedicated CLI interface for configuration management, implemented in deeptutor_cli/config_cmd.py. The command structure uses load_config_with_main("main.yaml") from deeptutor/services/config/loader.py to read and modify settings.

Display Current Configuration

View the active configuration with:

deeptutor config show

This command reads config/main.yaml and displays a consolidated view of current settings.

Modify Global Settings

Update configuration values using the set subcommand:

deeptutor config set system.language zh

This creates or updates data/user/settings/main.yaml with:

system:
  language: zh

Override Agent Parameters

Set user-specific agent constraints:

deeptutor config set agents.max_tokens 1024

This writes to data/user/settings/agents.yaml:

agents:
  max_tokens: 1024

Configuration Loading Architecture

The core configuration system resides in deeptutor/services/config/loader.py. This loader merges user-supplied YAML files with the common main.yaml and resolves configuration aliases.

Additionally, deeptutor/services/config/provider_runtime.py handles provider-specific sections, while deeptutor/utils/config_manager.py manages the data/user/settings/*.yaml files at runtime.

Summary

• DeepTutor uses .env.example templates for environment variables like API keys and database paths.
• config/main.yaml stores global server, logging, and provider settings, generated automatically on first run.
• config/agents.yaml defines unified defaults for LLM parameters including temperature and max_tokens.
• Per-user customizations live in data/user/settings/main.yaml and data/user/settings/agents.yaml.
• The deeptutor config CLI commands provide a programmatic interface for updating settings without manual file editing.
• The central loader in deeptutor/services/config/loader.py handles file merging and alias resolution at runtime.

Frequently Asked Questions

Where are the DeepTutor configuration files located?

DeepTutor configuration files reside in three primary locations: the root directory contains .env templates; config/ holds main.yaml and agents.yaml (generated at runtime); and data/user/settings/ stores per-user overrides. The config/ directory does not ship with the repository but is created automatically on first launch.

How do I change the LLM provider in DeepTutor?

Edit the providers.llm section in config/main.yaml to specify your desired provider name and API key. For per-user changes, use the CLI command deeptutor config set providers.llm.name <provider> which updates data/user/settings/main.yaml while preserving global defaults.

What is the difference between config/agents.yaml and data/user/settings/agents.yaml?

config/agents.yaml contains global agent defaults that apply to all users, while data/user/settings/agents.yaml contains overrides specific to the current user. The system merges these hierarchically, with user settings taking precedence over global defaults.

How does DeepTutor load configuration files at startup?

The platform uses load_config_with_main() from deeptutor/services/config/loader.py to merge configuration layers. It first loads the base main.yaml, then applies user-specific settings from data/user/settings/, resolving aliases and environment variable references like ${OPENAI_API_KEY} during the process.

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