# DeepTutor Configuration Files: A Complete Guide to Setup and Customization

> Master DeepTutor configuration files YAML and ENV. Learn setup and customization for API keys, server ports, LLM settings, and UI preferences. Optimize your DeepTutor experience.

- Repository: [✨Data Intelligence Lab@HKU✨/DeepTutor](https://github.com/HKUDS/DeepTutor)
- Tags: how-to-guide
- Published: 2026-04-08

---

**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`](https://github.com/HKUDS/DeepTutor/blob/main/config/main.yaml)

The [`config/main.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/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:

```yaml
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`](https://github.com/HKUDS/DeepTutor/blob/main/config/agents.yaml)

DeepTutor maintains unified agent-level defaults in [`config/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/config_cmd.py). The command structure uses `load_config_with_main("main.yaml")` from [`deeptutor/services/config/loader.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/config/loader.py) to read and modify settings.

### Display Current Configuration

View the active configuration with:

```bash
deeptutor config show

```

This command reads [`config/main.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/config/main.yaml) and displays a consolidated view of current settings.

### Modify Global Settings

Update configuration values using the `set` subcommand:

```bash
deeptutor config set system.language zh

```

This creates or updates [`data/user/settings/main.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/data/user/settings/main.yaml) with:

```yaml
system:
  language: zh

```

### Override Agent Parameters

Set user-specific agent constraints:

```bash
deeptutor config set agents.max_tokens 1024

```

This writes to [`data/user/settings/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/data/user/settings/agents.yaml):

```yaml
agents:
  max_tokens: 1024

```

## Configuration Loading Architecture

The core configuration system resides in [`deeptutor/services/config/loader.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/config/loader.py). This loader merges user-supplied YAML files with the common [`main.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/main.yaml) and resolves configuration aliases.

Additionally, [`deeptutor/services/config/provider_runtime.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/config/provider_runtime.py) handles provider-specific sections, while [`deeptutor/utils/config_manager.py`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/config/main.yaml)** stores global server, logging, and provider settings, generated automatically on first run.
- **[`config/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/config/agents.yaml)** defines unified defaults for LLM parameters including temperature and max_tokens.
- Per-user customizations live in **[`data/user/settings/main.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/data/user/settings/main.yaml)** and **[`data/user/settings/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/main.yaml) and [`agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/data/user/settings/main.yaml) while preserving global defaults.

### What is the difference between [`config/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/config/agents.yaml) and [`data/user/settings/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/data/user/settings/agents.yaml)?

[`config/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/config/agents.yaml) contains global agent defaults that apply to all users, while [`data/user/settings/agents.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/config/loader.py) to merge configuration layers. It first loads the base [`main.yaml`](https://github.com/HKUDS/DeepTutor/blob/main/main.yaml), then applies user-specific settings from `data/user/settings/`, resolving aliases and environment variable references like `${OPENAI_API_KEY}` during the process.