Skip to main content

​
Overview

The nanobot configuration system is built on Pydantic, providing type-safe configuration with automatic validation. All configuration models support both camelCase and snake_case keys, making them flexible for different configuration formats.

​
Root Configuration

​
Config

The root configuration object for nanobot.
​
agents
AgentsConfig
Agent configuration settings. See AgentsConfig.
​
channels
ChannelsConfig
Chat channel configuration. See ChannelsConfig.
​
providers
ProvidersConfig
LLM provider configuration. See providers documentation.
​
gateway
GatewayConfig
Gateway/server configuration. See GatewayConfig.
​
tools
ToolsConfig
Tools configuration. See ToolsConfig.

​
Environment Variables

All configuration can be set via environment variables using the prefix NANOBOT_ with double underscores for nesting: 
NANOBOT_AGENTS__DEFAULTS__MODEL=anthropic/claude-opus-4-5
NANOBOT_CHANNELS__TELEGRAM__ENABLED=true
NANOBOT_CHANNELS__TELEGRAM__TOKEN=your_token_here

​
Agent Configuration

​
AgentsConfig

​
defaults
AgentDefaults
default:"AgentDefaults()"
Default agent configuration settings.

​
AgentDefaults

Default settings applied to all agents.
​
workspace
str
default:"~/.nanobot/workspace"
Default workspace directory for agent operations.
​
model
str
default:"anthropic/claude-opus-4-5"
Default LLM model to use. Can include provider prefix (e.g., anthropic/claude-opus-4-5, openai/gpt-4).
​
provider
str
default:"auto"
Provider name (e.g., anthropic, openrouter) or auto for automatic detection based on model name.
​
maxTokens
int
default:"8192"
Maximum tokens for model responses.
​
temperature
float
default:"0.1"
Sampling temperature for model responses (0.0-2.0).
​
maxToolIterations
int
default:"40"
Maximum number of tool call iterations per conversation turn.
​
memoryWindow
int
default:"100"
Number of recent messages to keep in conversation memory.
​
reasoningEffort
str | null
default:"null"
Enables LLM thinking mode. Options: low, medium, high, or null to disable.

​
Gateway Configuration

​
GatewayConfig

HTTP server and gateway settings.
​
host
str
default:"0.0.0.0"
Host address to bind the server to.
​
port
int
default:"18790"
Port number for the gateway server.
​
heartbeat
HeartbeatConfig
default:"HeartbeatConfig()"
Heartbeat service configuration.

​
HeartbeatConfig

​
enabled
bool
default:"true"
Enable heartbeat monitoring service.
​
intervalS
int
default:"1800"
Heartbeat interval in seconds (default: 30 minutes).

​
Tools Configuration

​
ToolsConfig

Configuration for agent tools and capabilities.
​
web
WebToolsConfig
default:"WebToolsConfig()"
Web-related tools configuration.
​
exec
ExecToolConfig
default:"ExecToolConfig()"
Shell execution tool configuration.
​
restrictToWorkspace
bool
default:"false"
If true, restrict all tool file access to the workspace directory only.
​
mcpServers
dict[str, MCPServerConfig]
default:"{}"
MCP (Model Context Protocol) server configurations. Keys are server names.

​
WebToolsConfig

​
proxy
str | null
default:"null"
HTTP/SOCKS5 proxy URL for web tools (e.g., http://127.0.0.1:7890 or socks5://127.0.0.1:1080).
​
search
WebSearchConfig
default:"WebSearchConfig()"
Web search configuration.

​
WebSearchConfig

​
apiKey
str
default:""
Brave Search API key for web search functionality.
​
maxResults
int
default:"5"
Maximum number of search results to return.

​
ExecToolConfig

​
timeout
int
default:"60"
Command execution timeout in seconds.
​
pathAppend
str
default:""
Additional paths to append to PATH environment variable during execution.

​
MCPServerConfig

Configuration for MCP (Model Context Protocol) server connections.
​
type
'stdio' | 'sse' | 'streamableHttp' | null
default:"null"
Connection type. Auto-detected if omitted.
​
command
str
default:""
Command to run for stdio connections (e.g., npx).
​
args
list[str]
default:"[]"
Command-line arguments for stdio connections.
​
env
dict[str, str]
default:"{}"
Extra environment variables for stdio connections.
​
url
str
default:""
Endpoint URL for HTTP/SSE connections.
​
headers
dict[str, str]
default:"{}"
Custom HTTP headers for HTTP/SSE connections.
​
toolTimeout
int
default:"30"
Tool call timeout in seconds.

​
Complete Example

# config.yml
agents:
  defaults:
    workspace: ~/.nanobot/workspace
    model: anthropic/claude-opus-4-5
    provider: auto
    maxTokens: 8192
    temperature: 0.1
    maxToolIterations: 40
    memoryWindow: 100
    reasoningEffort: medium

gateway:
  host: 0.0.0.0
  port: 18790
  heartbeat:
    enabled: true
    intervalS: 1800

tools:
  restrictToWorkspace: false
  web:
    proxy: null
    search:
      apiKey: ${BRAVE_API_KEY}
      maxResults: 5
  exec:
    timeout: 60
    pathAppend: ""
  mcpServers:
    filesystem:
      type: stdio
      command: npx
      args:
        - -y
        - "@modelcontextprotocol/server-filesystem"
        - /path/to/allowed/dir
      toolTimeout: 30

​
Validation

All configuration is validated using Pydantic:
  • Type checking: Ensures all values match expected types
  • Default values: Automatically applies defaults for missing fields
  • Custom validators: Enforces business rules and constraints
  • Case flexibility: Accepts both camelCase and snake_case keys

​
Common Validation Errors

# Invalid type
agents:
  defaults:
    maxTokens: "8192"  # Error: expected int, got str

# Invalid enum value
agents:
  defaults:
    reasoningEffort: "ultra"  # Error: must be low/medium/high or null

# Missing required field (when defaults don't apply)
mcpServers:
  myserver:
    type: stdio
    # Error: command required for stdio type

​
Accessing Configuration

The configuration is loaded at startup and accessible throughout the application: 
from nanobot.config.schema import Config

# Load configuration
config = Config()

# Access workspace path (automatically expanded)
workspace = config.workspace_path

# Get provider for a model
provider = config.get_provider("claude-opus-4-5")
api_key = config.get_api_key("claude-opus-4-5")
api_base = config.get_api_base("claude-opus-4-5")

# Get provider name
provider_name = config.get_provider_name("claude-opus-4-5")

Build docs developers (and LLMs) love

Get started for freeTalk to us