Nanobot Config File Location: Default Path and Customization Guide

Nanobot stores its configuration in ~/.nanobot/config.json by default, but you can relocate it programmatically using set_config_path() before loading or saving.

The HKUDS/nanobot repository persists agent settings in a JSON-based configuration file. Understanding the default location and override mechanisms is essential for deployment automation, testing environments, and multi-agent setups.

Default Nanobot Config File Location

According to the source code in nanobot/config/loader.py, the library resolves the configuration path through the get_config_path() function (lines 27‑31). When no custom path is set, the function returns:

Path.home() / ".nanobot" / "config.json"

This places the config file in a hidden directory within the user's home folder. The library creates this file automatically during the first load_config() call if it does not exist.

Examining the Path Resolution Logic

The implementation checks a global variable _current_config_path before falling back to the default:

def get_config_path() -> Path:
    """Get the configuration file path."""
    if _current_config_path:
        return _current_config_path
    return Path.home() / ".nanobot" / "config.json"

How to Customize the Config File Path

To store configuration elsewhere, call set_config_path() before any load or save operations. This function updates the global state that get_config_path() inspects (lines 21‑24):

def set_config_path(path: Path) -> None:
    """Set the current config path (used to derive data directory)."""
    global _current_config_path
    _current_config_path = path

This pattern supports project-specific configurations or portable deployments where the home directory is not appropriate.

Implementing a Custom Configuration Path

from pathlib import Path
from nanobot.config.loader import set_config_path, load_config, save_config

# Define an alternate location

custom_path = Path("./project_config.json")
set_config_path(custom_path)

# Load or create the config at the new location

cfg = load_config()
cfg.api.port = 8080
save_config(cfg)  # Writes to ./project_config.json

Temporary Configuration Overrides for Testing

For unit tests or ephemeral environments, you can redirect the configuration to a temporary directory. This prevents test data from polluting the default ~/.nanobot/ directory:

import tempfile
from pathlib import Path
from nanobot.config.loader import set_config_path, load_config, save_config

with tempfile.TemporaryDirectory() as td:
    temp_path = Path(td) / "config.json"
    set_config_path(temp_path)
    
    cfg = load_config()  # Creates file in temp directory

    # ... test logic ...

    save_config(cfg)     # Persisted only within temp scope

Key Source Files for Configuration Management

The configuration system spans three primary modules:

• nanobot/config/loader.py — Contains get_config_path(), set_config_path(), load_config(), and save_config() utilities for file I/O and path resolution.
• nanobot/config/schema.py — Defines the Pydantic Config model that validates and structures the JSON content.
• nanobot/utils/helpers.py — Provides atomic write operations used by save_config() to prevent corruption during concurrent access.

Summary

• Nanobot uses ~/.nanobot/config.json as the default configuration location.
• The get_config_path() function in nanobot/config/loader.py implements the resolution logic.
• Use set_config_path() to programmatically override the storage location before initialization.
• Temporary directories work for isolated testing environments without side effects.

Frequently Asked Questions

Where is the Nanobot config file stored by default?

By default, Nanobot stores its configuration in $HOME/.nanobot/config.json. The get_config_path() function in nanobot/config/loader.py constructs this path using Path.home() unless a custom location has been set.

How do I change the Nanobot configuration file location?

Call set_config_path() from nanobot.config.loader and pass a pathlib.Path object before invoking load_config(). This updates the internal global variable _current_config_path that subsequent operations reference.

Can I use multiple config files with Nanobot?

Yes. By calling set_config_path() with different paths before loading, you can maintain separate configurations for different agents or environments. Each load_config() call respects the most recently set path.

What format does the Nanobot config file use?

The configuration file uses JSON format. The nanobot/config/schema.py module defines a Pydantic schema that validates the structure during load and save operations, ensuring type safety for fields like api.port and data directories.

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