DeepSeek TUI Configuration System: Profiles and Environment Variable Overrides

DeepSeek TUI loads its runtime settings from a four-layer hierarchy where CLI flags take precedence over environment variables, which in turn override TOML configuration profiles and built-in defaults.

The DeepSeek TUI (Hmbown/DeepSeek-TUI) provides a deterministic, multi-layered configuration system designed for both interactive use and CI/CD automation. It merges global settings, per-project overlays, named profiles, and environment-specific overrides to determine final runtime behavior, all implemented in the crates/config/src/lib.rs core library.

Configuration File Locations and Structure

DeepSeek TUI reads TOML configuration from two primary locations, merging them sequentially.

First, the global configuration at ~/.deepseek/config.toml establishes base settings. Second, if the TUI starts inside a Git workspace containing .deepseek/config.toml, those values are merged on top via the load_project_config function (lines 776–787 of crates/config/src/lib.rs). This overlay can replace the entire providers table or specific fields without modifying your global settings.

A valid configuration file contains top-level keys (e.g., api_key, default_text_model) and optional nested tables for providers and profiles:

api_key = "PERSONAL_KEY"
default_text_model = "deepseek-v4-pro"
base_url = "https://api.deepseek.com"

[providers.deepseek]
api_key = "PROVIDER_SPECIFIC_KEY"

[profiles.work]
api_key = "WORK_KEY"
base_url = "https://enterprise.deepseek.com"

Understanding Configuration Precedence

The resolver follows a strict precedence order to guarantee predictable behavior. When a key is defined in multiple layers, the system picks the value from the highest-priority layer that defines it:

1. CLI flags (e.g., --model, --profile) – Highest priority.
2. Environment variables (e.g., DEEPSEEK_API_KEY) – Override file settings.
3. Configuration file – Merged global, project, and active profile values.
4. Built-in defaults – Hardcoded provider URLs and models (e.g., NVIDIA NIM defaults to https://integrate.api.nvidia.com/v1) – Lowest priority.

The resolve_runtime_options function (lines 602–630 of crates/config/src/lib.rs) implements this logic, checking CLI overrides first, then EnvRuntimeOverrides, then file-based values, and finally falling back to provider-specific defaults defined at lines 690–698.

Working with Profiles

Profiles allow you to define isolated configuration sets for different contexts (e.g., "work", "personal", or "nvidia-nim") within a single file.

A profile is a named table under the [profiles] section. It can contain any top-level key, including api_key, base_url, provider, or default_text_model.

[profiles.nvidia-nim]
provider = "nvidia-nim"
api_key = "NVIDIA_KEY"
base_url = "https://integrate.api.nvidia.com/v1"
default_text_model = "deepseek-ai/deepseek-v4-pro"

Activate a profile using the --profile flag or the DEEPSEEK_PROFILE environment variable:

deepseek --profile nvidia-nim

# or

export DEEPSEEK_PROFILE=nvidia-nim
deepseek

If the requested profile does not exist, the TUI aborts with a clear error listing available profiles.

Environment Variable Overrides

All top-level configuration keys map to a DEEPSEEK_* environment variable, read by EnvRuntimeOverrides::load. These variables override any value coming from the file, regardless of whether a profile is active.

Common environment variables include:

• DEEPSEEK_API_KEY – Overrides the global api_key (or provider-specific key when a provider is selected).
• DEEPSEEK_BASE_URL – Overrides the global base_url.
• DEEPSEEK_MODEL or DEEPSEEK_DEFAULT_TEXT_MODEL – Overrides the default_text_model setting.
• DEEPSEEK_PROVIDER – Forces a specific provider (deepseek, nvidia-nim, fireworks, etc.).
• DEEPSEEK_ALLOW_SHELL – Enables the sandboxed shell tool when set to true or 1.
• DEEPSEEK_APPROVAL_POLICY – Sets the runtime approval policy (on-request, untrusted, never).
• DEEPSEEK_SANDBOX_MODE – Sets the sandbox level (read-only, workspace-write, danger-full-access).

Provider-specific variables (e.g., NVIDIA_NIM_API_KEY, FIREWORKS_BASE_URL) override values inside the corresponding provider sub-tables without needing to specify a profile.

Runtime Resolution in Code

You can programmatically resolve the final configuration using the Rust API exposed in crates/config/src/lib.rs. This is useful for building tools that need to verify settings before launching the TUI:

use deepseek_config::ConfigStore;
use deepseek_config::{CliRuntimeOverrides, ProviderKind};

let store = ConfigStore::load(None).unwrap(); // Loads ~/.deepseek/config.toml
let cli = CliRuntimeOverrides {
    provider: Some(ProviderKind::NvidiaNim),
    model: Some("deepseek-v4-flash".into()),
    ..Default::default()
};

// Returns final merged options
let opts = store.config.resolve_runtime_options(&cli);

The resolve_runtime_options_with_secrets variant handles sensitive values like API keys securely.

Practical Configuration Examples

Define Multiple Profiles

Create ~/.deepseek/config.toml with distinct settings for work and personal use:

api_key = "PERSONAL_KEY"
default_text_model = "deepseek-v4-pro"

[profiles.work]
api_key = "WORK_KEY"
base_url = "https://api.deepseek.com"

Switch Contexts via Command Line

Override the active profile for a single invocation:

deepseek --profile work        # Uses WORK_KEY and work base URL

Temporarily Override with Environment Variables

Change a setting for the current shell session without editing files:

export DEEPSEEK_MODEL=deepseek-v4-flash
deepseek  # Runs with the flash model regardless of profile

Demonstrate Precedence

CLI flags win over environment variables, which win over profiles:

export DEEPSEEK_MODEL=deepseek-v4-pro
deepseek --profile work --model deepseek-v4-flash

# Result: model is "deepseek-v4-flash" (CLI flag takes precedence)

Summary

• Four-layer hierarchy: CLI flags > Environment variables > Config file (global + project + profile) > Built-in defaults.
• Project overlays: Per-project .deepseek/config.toml files are merged over global settings via load_project_config.
• Profile activation: Use [profiles.name] tables and activate with --profile or DEEPSEEK_PROFILE.
• Env mapping: All config keys have a DEEPSEEK_* equivalent that overrides file values, implemented in EnvRuntimeOverrides.

Frequently Asked Questions

What is the exact order of precedence for DeepSeek TUI configuration?

The resolver evaluates options in this order: CLI flags have the highest priority, followed by environment variables, then configuration file values (merged global, project overlay, and active profile), and finally hardcoded built-in defaults. This logic is centralized in the resolve_runtime_options function in crates/config/src/lib.rs.

How do I create and activate a configuration profile?

Add a [profiles.<name>] table to your ~/.deepseek/config.toml file containing the keys you want to override. Activate it by passing --profile <name> to the deepseek command or by setting the DEEPSEEK_PROFILE=<name> environment variable. If the profile name is invalid, the application exits with a list of available profiles.

Can I use environment variables for all configuration settings?

Yes. Any top-level TOML key can be set via an environment variable using the DEEPSEEK_<KEY> naming convention. For example, DEEPSEEK_API_KEY overrides the api_key field, and DEEPSEEK_ALLOW_SHELL controls sandboxed shell execution. Provider-specific keys use the pattern <PROVIDER>_API_KEY (e.g., NVIDIA_NIM_API_KEY).

Where does DeepSeek TUI look for configuration files?

The system first loads the global configuration from ~/.deepseek/config.toml. If executed within a Git repository, it searches for <workspace>/.deepseek/config.toml and merges those settings over the global ones. This merging logic is handled by the load_project_config implementation in crates/config/src/lib.rs.

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