Configuration (loom.toml)
Relevant source files
The following files were used as context for generating this wiki page:
The loom.toml file is the central configuration hub for any Loom project. It provides a declarative way to define the behavior of the Loom runtime, configure connections to external services like LLMs, manage agent-specific settings, and orchestrate multi-agent systems. The configuration is loaded at runtime by the Python SDK, allowing for flexible and environment-aware setups.
The system is designed to be highly configurable, supporting environment variable expansion and automatic loading from .env files. This allows developers to separate secrets and environment-specific settings from the main configuration file, promoting better security and portability. The Python class ProjectConfig in loom.runtime.config is the primary data structure that holds the parsed configuration.
Sources: loom-py/src/loom/runtime/config.py, README.md:121-130
Configuration Loading Process
The loom.toml file is parsed into a ProjectConfig object. The loading process automatically discovers and loads .env files and expands environment variables, providing a flexible way to manage settings.
The diagram below illustrates the configuration loading flow.
This diagram shows the sequence of operations when ProjectConfig.load() is called, including .env file discovery and environment variable expansion.
Sources: loom-py/src/loom/runtime/config.py:173-207
Environment Variable Expansion
The configuration loader supports expanding environment variables using both ${VAR} and $VAR syntax. It also automatically searches for and loads a .env file in the same directory as loom.toml, parent directories, or the current working directory. This allows for secure management of secrets like API keys.
Sources: loom-py/src/loom/runtime/config.py:58-90
Configuration Schema
The loom.toml file is structured into several top-level TOML tables. The core data structures are defined as Python dataclasses within loom-py/src/loom/runtime/config.py.
The diagram below shows the relationship between the main configuration classes.
This class diagram represents the Python data classes that model the loom.toml configuration structure.
Sources: loom-py/src/loom/runtime/config.py
Core Sections
[bridge]
This section configures the connection to the gRPC bridge, which is the gateway to the Rust Core runtime.
| Key | Type | Default | Description |
|---|---|---|---|
address | str | "127.0.0.1:50051" | The gRPC address of the bridge server. |
mode | str | "full" | Runtime mode. Can be "full" or "bridge-only". |
version | str | "latest" | The runtime version to use. |
timeout_sec | int | 30 | Connection timeout in seconds. |
Sources: loom-py/src/loom/runtime/config.py:93-100, loom-py/src/loom/runtime/config.py:221-227
[dashboard]
This section controls the built-in observability dashboard.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Enables or disables the dashboard server. |
port | int | 3030 | The HTTP port for the dashboard. |
host | str | "127.0.0.1" | The host address to bind the dashboard server to. |
Sources: loom-py/src/loom/runtime/config.py:126-132, loom-py/src/loom/runtime/config.py:229-235
[llm]
This section is for defining one or more Large Language Model (LLM) providers. Each provider is a sub-table under [llm], for example, [llm.deepseek].
| Key | Type | Default | Description |
|---|---|---|---|
type | str | "http" | The type of the provider. |
api_key | str | None | The API key for the LLM service. Can use env var expansion. |
api_base | str | None | The base URL for the LLM API endpoint. |
model | str | None | The specific model name to use (e.g., "deepseek-chat"). |
max_tokens | int | 2048 | The maximum number of tokens for the model to generate. |
temperature | float | 0.7 | The sampling temperature for generation. |
timeout_sec | int | 30 | Request timeout in seconds. |
Example:
# From apps/market-analyst/loom.toml
[llm.deepseek]
type = "http"
api_key = "${DEEPSEEK_API_KEY}"
api_base = "https://api.deepseek.com"
model = "deepseek-chat"
max_tokens = 4096
temperature = 0.7
Sources: apps/market-analyst/loom.toml:2-9, loom-py/src/loom/runtime/config.py:103-116, loom-py/src/loom/runtime/config.py:237-256
[mcp]
This section configures Model Context Protocol (MCP) servers, which are external processes that provide additional tools to agents.
| Key | Type | Default | Description |
|---|---|---|---|
command | str | "" | The command to execute to start the server (e.g., "npx"). |
args | list[str] | [] | A list of arguments for the command. |
env | dict[str, str] | {} | Environment variables to set for the server process. |
Example:
# From apps/chat-assistant/loom.toml
[mcp.brave]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
env = { BRAVE_API_KEY = "${BRAVE_API_KEY}" }
Sources: apps/chat-assistant/loom.toml:10-13, loom-py/src/loom/runtime/config.py:119-124, loom-py/src/loom/runtime/config.py:258-270
[agents]
This section allows for agent-specific configurations. Each agent is defined as a sub-table, like [agents.planner-agent]. The content of this section is a free-form dictionary, allowing developers to define any custom parameters their agents might need.
Example from market-analyst:
The market-analyst application uses this section to configure its various agents, such as the data source for the data-agent and the LLM provider for the planner-agent.
# From apps/market-analyst/loom.toml
[agents.data-agent]
data_source = "okx"
exchange = "okx"
symbols = ["BTC-USDT", "ETH-USDT"]
[agents.planner-agent]
llm_provider = "deepseek"
timeout_ms = 3000
[agents.executor-agent]
enable_trading = false
min_order_size = 0.001
max_order_size = 0.01
Sources: apps/market-analyst/loom.toml:11-25, loom-py/src/loom/runtime/config.py:141-142, loom-py/src/loom/runtime/config.py:272-288
Conclusion
The loom.toml file is a cornerstone of the Loom framework, providing a powerful and flexible mechanism for configuring every aspect of an AI agent system. Its support for environment variables, clear separation of concerns through distinct sections, and extensibility for agent-specific settings make it well-suited for both simple and complex multi-agent applications. By centralizing configuration, loom.toml simplifies deployment, enhances maintainability, and allows developers to quickly adapt their systems to different environments and requirements.
Sources: loom-py/src/loom/runtime/README.md, apps/market-analyst/README.md:65-103