# How Configuration Is Managed in DeepSeek-Reasonix

> Discover how DeepSeek-Reasonix manages configuration using a layered TOML system. Learn how it merges command-line flags, project, and user configs with defaults for seamless operation.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-23

---

**DeepSeek-Reasonix uses a layered TOML-based configuration system that merges command-line flags, project-level [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), user-wide [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml), and built-in defaults from the `internal/config` package, normalizing values and expanding environment variables for secrets.**

DeepSeek-Reasonix centralizes its runtime options in the `Config` struct defined in [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go). The configuration management system follows a strict resolution order, applies deep merging strategies, and provides normalization helpers to ensure the agent and desktop UI receive validated settings. Understanding how configuration is managed in DeepSeek-Reasonix allows developers to customize model providers, sandbox permissions, and interface themes without modifying the source code.

## Configuration Resolution Order

The configuration loader implements a strict precedence hierarchy where higher-priority sources override lower ones. The system evaluates sources in the following order:

1. **Command-line flags** – Runtime arguments passed to the binary take highest precedence.
2. **[`./reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/./reasonix.toml)** – Project-level configuration located in the current working directory.
3. **User-wide [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml)** – Located in the OS-specific configuration directory (e.g., `~/.config/reasonix/config.toml` on Linux systems).
4. **Built-in defaults** – Hardcoded values returned by the `Default()` function at lines 59-112 in [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go).

Secrets such as API keys are never persisted in TOML files. Instead, the system uses `*_env` fields (e.g., `api_key_env`) to reference environment variables that are expanded during the `ExpandEnv()` phase.

## Core Configuration Types

The `Config` struct defined at lines 44-64 in [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) serves as the central registry for all runtime options. Key sub-structures include:

- **`Config`** – The top-level container with fields for `DefaultModel`, `UI`, `Desktop`, `Agent`, `Providers`, `Tools`, `Network`, and `Sandbox`.
- **`UIConfig`** – CLI appearance settings including `Theme`, `ThemeStyle`, `ShortcutLayout`, and `ShowReasoning`.
- **`DesktopConfig`** – Desktop-specific preferences such as `Language`, `LayoutStyle`, `CloseBehavior`, and `DisplayMode`, independent of CLI settings.
- **`AgentConfig`** – Agent behavior controls including `MaxSteps`, `PlannerModel`, `AutoPlan`, and `ReasoningLanguage`.
- **`ProviderEntry`** – Model provider definitions with `BaseURL`, `APIKeyEnv`, `ContextWindow`, and pricing metadata (see default providers at lines 108-110).
- **`ToolsConfig`** – Enabled tools and tuning parameters like `BashTimeoutSeconds`, `BackgroundJobs`, and `Search` engine settings.
- **`NetworkConfig`** – Outbound HTTP proxy handling via `ProxyMode`, `ProxyURL`, and `NoProxy` lists (defined at lines 27-33 and 52-62).
- **`SandboxConfig`** – File-writer confinement settings including `WorkspaceRoot`, `AllowWrite`, and `Bash` sandboxing rules (defined at lines 87-94).
- **`PermissionsConfig`** – Per-tool permission policies using `Mode`, `Allow`, `Ask`, and `Deny` lists (defined at lines 57-60).

All structs use TOML tags for direct mapping from configuration files.

## Default Configuration Values

When no user configuration files exist, the `Default()` function initializes a fully populated `Config` instance with the following sensible defaults:

- **`DefaultModel`**: `"deepseek-flash"` – The fallback model for all operations.
- **`CredentialsStore`**: `CredentialsStoreAuto` – Automatic secret handling.
- **`UI.Theme`** and **`Desktop.Theme`**: `"auto"` – Adaptive light/dark theming.
- **`Agent.AutoPlan`**: `"off"` – Manual planning mode unless explicitly enabled.
- **`Sandbox.Bash`**: `"enforce"` – Bash sandboxing enabled by default (macOS only).
- **`Network.ProxyMode`**: `netclient.ModeAuto` – Respects system proxy settings unless overridden.
- **Pre-registered providers**: `deepseek-flash` and `deepseek-pro` with pricing and balance URLs.

## Loading and Merging Process

The CLI entry point at [`cmd/reasonix/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go) orchestrates the configuration loading sequence:

```go
// Conceptual flow from the implementation
func LoadConfig() (*config.Config, error) {
    // 1. Start with built-in defaults (lines 59-112)
    cfg := config.Default()
    
    // 2. Overlay user-wide config if present
    if userCfg, _ := config.LoadUserFile(); userCfg != nil {
        cfg = cfg.Merge(userCfg)
    }
    
    // 3. Overlay project-level reasonix.toml if present
    if projCfg, _ := config.LoadProjectFile(); projCfg != nil {
        cfg = cfg.Merge(projCfg)
    }
    
    // 4. Apply CLI flags (highest precedence)
    cfg.ApplyFlags(flagSet)
    
    // 5. Expand environment variables
    cfg.ExpandEnv()
    
    // 6. Validate identifiers
    cfg.Validate()
    
    return cfg, nil
}

```

The `Merge()` method performs deep merging respecting TOML tags, while `Validate()` checks identifiers such as skill names and provider names.

## Normalization and Helper Methods

The `internal/config` package provides normalization methods that convert raw TOML values into canonical forms:

- **`UITheme()`** and **`UIThemeStyle()`** – Map user strings like `"dark"` or `"workbench"` to fixed identifiers.
- **`DesktopTheme()`** and **`DesktopLayoutStyle()`** – Resolve desktop UI preferences into validated values.
- **`NetworkProxySpec()`** – Builds a `netclient.ProxySpec` from proxy fields, expanding `${VAR}` placeholders.
- **`WriteRoots()`** – Resolves workspace and extra write directories for sandbox confinement.
- **`SkillCustomPaths()`**, **`SkillExcludedPaths()`**, and **`DisabledSkillNames()`** – Handle skill-discovery configuration.

These helpers ensure the rest of the system always receives clean, validated data regardless of input formatting.

## Environment Variables and Secrets

Sensitive values use indirect references to prevent credential leakage. Fields ending in `_env` specify the environment variable name containing the actual secret:

```toml
[providers.deepseek]
api_key_env = "DEEPSEEK_API_KEY"

```

During the `ExpandEnv()` phase, the loader replaces `${VAR}` placeholders and resolves `*_env` fields. This design keeps secrets out of version-controlled TOML files while maintaining full configurability.

## Accessing Configuration in Code

Application code retrieves settings through the centralized `Config` API without parsing TOML directly:

```go
cfg, err := config.LoadConfig()
if err != nil {
    log.Fatalf("failed to load config: %v", err)
}

// Retrieve resolved proxy specification
proxySpec := cfg.NetworkProxySpec()
fmt.Printf("Proxy mode: %s, URL: %s\n", proxySpec.Mode, proxySpec.URL)

// Check desktop update preferences
if cfg.DesktopCheckUpdates() {
    fmt.Println("Will check for updates on startup")
}

// Access agent step limits
maxSteps := cfg.Agent.MaxSteps

```

## Summary

- DeepSeek-Reasonix uses a four-layer resolution order: CLI flags override project [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), which overrides user [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml), which overrides `Default()` values from [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go).
- The `Config` struct (lines 44-64) aggregates all settings via tagged sub-structures for UI, Desktop, Agent, Providers, Tools, Network, and Sandbox.
- Secrets use `*_env` fields rather than hardcoded values, expanded during the `ExpandEnv()` phase.
- Helper methods like `NetworkProxySpec()` and `UITheme()` normalize raw values into canonical forms.
- The CLI entry point at [`cmd/reasonix/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go) orchestrates loading, merging, validation, and environment expansion.

## Frequently Asked Questions

### Where does DeepSeek-Reasonix store its configuration files?

Project-level settings reside in [`./reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/./reasonix.toml) in the current working directory. User-wide settings are stored in [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml) within the OS-specific configuration directory, such as `~/.config/reasonix/` on Linux or `~/Library/Application Support/reasonix/` on macOS.

### How do I add a custom model provider without modifying the source code?

Add a new `[[providers]]` entry to your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file. Specify the `Name`, `Kind`, `BaseURL`, `Model`, and `APIKeyEnv` fields. The system automatically validates the provider entry during the `Validate()` phase and makes it available to the agent runtime.

### Why are my API keys not showing up in the configuration file?

DeepSeek-Reasonix never stores API keys in TOML files for security reasons. Instead, set the `api_key_env` field to reference an environment variable (e.g., `api_key_env = "DEEPSEEK_API_KEY"`), and ensure that variable is set in your shell before launching the application.

### How do I override a specific setting for a single command?

Use command-line flags, which have the highest precedence in the resolution order. The CLI parser in [`cmd/reasonix/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go) applies flag values after loading all configuration files, allowing temporary overrides without editing persistent configuration files.