# How to Configure Config File Paths and Precedence in Reasonix

> Learn how to configure config file paths and precedence in Reasonix. Understand the loading hierarchy from defaults to CLI flags for seamless project setup.

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

---

**Reasonix loads configuration from a hierarchy of built‑in defaults, legacy JSON, global TOML, workspace TOML, project‑level TOML, environment variables, and CLI flags, with later sources overriding earlier ones according to the precedence defined in [`internal/config/load.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/load.go).**

The DeepSeek-Reasonix project implements a sophisticated configuration system that merges multiple sources according to a strict precedence order. Understanding how to configure config file paths and precedence in Reasonix is essential for controlling behavior across global user settings, workspace-specific requirements, and temporary overrides. The configuration logic resides in the `internal/config` package and supports TOML, JSON, and environment-based configuration.

## Configuration Precedence Hierarchy

Reasonix applies a seven-layer configuration stack, implemented primarily in [[`internal/config/load.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/load.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/load.go). The system merges successive layers using `config.Mutate()` from [[`internal/config/mutate.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/mutate.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/mutate.go), with each layer overwriting conflicting keys from previous layers.

The precedence order from lowest to highest priority is:

1. **Built‑in defaults** – Hard‑coded fallback values defined in [[`internal/config/default_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/default_test.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/default_test.go).
2. **Legacy global config** – The JSON configuration at `$HOME/.reasonix/config.json`, maintained for v0.x compatibility as handled in [[`internal/config/migrate.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/migrate.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/migrate.go).
3. **Global TOML config** – The user‑wide configuration file located at `$REASONIX_HOME/config.toml`, resolved via `config.MemoryUserDir()` in [[`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/paths.go).
4. **Workspace TOML config** – The [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file at the root of the current workspace.
5. **Project TOML config** – The [`.reasonix/config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.reasonix/config.toml) file inside a specific project directory, referenced in [[`internal/config/load_project_default_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/load_project_default_test.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/load_project_default_test.go).
6. **Environment variables** – Variables prefixed with `REASONIX_` (e.g., `REASONIX_LOG_LEVEL`), processed by [[`internal/config/environment_config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/environment_config.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/environment_config.go).
7. **Command‑line flags** – Arguments passed directly to the `reasonix` CLI, parsed in the `cmd/` directory.

## Config File Path Resolution

### Global Configuration Directory

The global user configuration location is determined by `config.MemoryUserDir()` in [[`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/paths.go). This function follows OS‑specific conventions: it respects XDG directories on Linux and `%APPDATA%` on Windows. The function `config.ReasonixManagedConfigPaths()` returns the set of Reasonix‑owned files that may be written outside the workspace, including [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml) and [`credentials.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/credentials.json). Writes to these managed files are controlled by an interactive approval flow defined in [[`internal/tool/builtin/managed_config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/builtin/managed_config.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/tool/builtin/managed_config.go).

### Workspace and Project Configuration

When Reasonix opens a workspace, it automatically searches for [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) at the workspace root. This file overrides any global settings. Additionally, individual projects may contain a [`.reasonix/config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.reasonix/config.toml) file that is merged on top of the workspace configuration, allowing repository‑specific settings to travel with the code.

## Practical Configuration Examples

### Reading Configuration Programmatically

To access the fully merged configuration in Go code:

```go
import (
    "fmt"
    "reasonix/internal/config"
)

func example() {
    cfg := config.Default()               // loads with full precedence
    logLevel := cfg.GetString("log.level") // e.g., "info" or "debug"
    fmt.Println("Current log level:", logLevel)
}

```

This example references the `config.Default()` function from [[`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/config/config.go).

### Overriding via Environment Variables

Any configuration key can be overridden using the `REASONIX_` prefix:

```bash
export REASONIX_LOG_LEVEL=debug
reasonix run mytask

```

The [`environment_config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/environment_config.go) module processes these variables after all file‑based configurations have been merged.

### Using Custom Global Config Paths

You can redirect the global configuration location using the `REASONIX_HOME` environment variable or specify an explicit file via CLI flags:

```bash
export REASONIX_HOME=/custom/path
reasonix --config /custom/path/config.toml run mytask

```

Note that the explicit `--config` flag takes the highest precedence among all configuration sources.

### Creating a Workspace Configuration

Create a [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file at your workspace root to set local defaults:

```toml
[log]
level = "warn"

[sandbox]
allow_write = ["$HOME/tmp", "./data"]

```

When you execute `reasonix` within this workspace, the sandbox `allow_write` list from this file overrides global defaults, while the `log.level` setting affects only this workspace unless superseded by environment variables or flags.

## Summary

- **Reasonix uses a seven‑layer precedence stack**: built‑in defaults → legacy JSON → global TOML → workspace TOML → project TOML → environment variables → CLI flags.
- **Path resolution** relies on `config.MemoryUserDir()` for global directories and supports XDG/%APPDATA% conventions via [`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go).
- **Workspace and project configs** use [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) and [`.reasonix/config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.reasonix/config.toml) respectively, loaded by [`internal/config/load.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/load.go).
- **Environment variables** prefixed with `REASONIX_` override file settings and are handled in [`internal/config/environment_config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/environment_config.go).
- **Managed config writes** to global files require interactive approval through [`internal/tool/builtin/managed_config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/builtin/managed_config.go).

## Frequently Asked Questions

### What is the exact order of precedence for Reasonix configuration files?

Reasonix loads configuration in the following order, with each step overwriting conflicts from the previous: built‑in defaults, legacy `$HOME/.reasonix/config.json`, global `$REASONIX_HOME/config.toml`, workspace [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), project [`.reasonix/config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.reasonix/config.toml), `REASONIX_*` environment variables, and finally CLI flags. This hierarchy is implemented in [`internal/config/load.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/load.go) and merged using `config.Mutate()`.

### How do I temporarily override a specific configuration value without editing files?

Use environment variables with the `REASONIX_` prefix followed by the uppercase key name. For example, setting `REASONIX_LOG_LEVEL=debug` will override the log level for that session without modifying any TOML files. The [`internal/config/environment_config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/environment_config.go) file handles this resolution after all file configurations are loaded.

### Where does Reasonix store global user configuration by default?

The global configuration directory is resolved by `config.MemoryUserDir()` in [`internal/config/paths.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/paths.go), which follows OS conventions: typically `~/.config/reasonix/` on Linux (respecting `$XDG_CONFIG_HOME`), `%APPDATA%\reasonix\` on Windows, and `~/Library/Application Support/reasonix/` on macOS. The main configuration file is [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml) within this directory.

### Can I prevent Reasonix from writing to global config files automatically?

Yes. Writes to Reasonix‑managed global config files (such as [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml) and [`credentials.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/credentials.json)) are gated by an interactive approval system defined in [`internal/tool/builtin/managed_config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/builtin/managed_config.go). This ensures that automated processes cannot modify global settings without explicit user consent.