Configuration Guide

Lattice's behavior is controlled through a TOML configuration file that lives at ~/.lovelace/lattice/config.toml. This file tells the daemon which LLM providers to use, how many agents can run concurrently, what resource limits to enforce, and how verbose logging should be. Understanding how to structure this configuration file and when changes take effect is essential to using Lattice effectively.

Understanding Configuration

The daemon loads configuration from: --config flag, LATTICE_CONFIG_PATH environment variable, ~/.lovelace/lattice/config.toml, or built-in defaults (in that order). Configuration uses TOML format with sections like [daemon] and [providers.ollama] containing key-value pairs.

Creating Your First Configuration

Let's create a basic configuration file that sets up Ollama as the default provider. First, ensure the configuration directory exists, then write a minimal config that gets you running:

mkdir -p ~/.lovelace/lattice
cat > ~/.lovelace/lattice/config.toml << 'EOF'
[orchestrator]
default_provider = "ollama"

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3.2"
enabled = true

[daemon]
max_agents = 10
log_level = "info"
EOF

This configuration tells the daemon to use Ollama as its primary LLM provider, connecting to the Ollama service running on localhost port 11434. It sets llama3.2 as the default model and allows up to 10 agents to run concurrently. The logging level is set to "info", which provides useful feedback without being overwhelming.

After creating or modifying the configuration file, you must restart the daemon for changes to take effect. The daemon only reads configuration at startup, so a running daemon won't pick up changes until you stop and start it:

lattice-ctl daemon stop
lattice-ctl daemon start

Provider Configuration

The heart of Lattice configuration is defining which LLM providers you want to use. Providers fall into two categories: local models that run on your machine and cloud APIs that execute remotely.

For local models like Ollama or LM Studio, you specify connection details like the base URL where the model server is running. The local models guide walks through setting up Ollama and LM Studio in detail, including how to download models, configure endpoints, and tune performance for your hardware.

Cloud providers like Anthropic, OpenAI, and Google require API credentials rather than local server configuration. Each provider needs an API key that you either store in an environment variable or reference in your configuration. The cloud providers guide explains how to obtain API keys, configure them securely, and manage costs when using cloud LLMs.

The [orchestrator] section of your configuration determines which provider is used by default. When you create an agent or session without specifying a provider, the daemon uses this default. You can configure multiple providers simultaneously and switch between them as needed:

[orchestrator]
default_provider = "ollama"  # Use Ollama by default

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3.2"
enabled = true

[providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
default_model = "claude-sonnet-4-6"
enabled = true

With this setup, the daemon uses Ollama by default but can also access Anthropic when you explicitly request it. This flexibility lets you use local models for most work while keeping cloud access available for tasks requiring more powerful models.

Daemon Settings

The [daemon] section controls operational parameters:

Concurrency: max_agents limits concurrent agents (default: 10). Balance system resources against parallelism needs—higher values enable more concurrent work but consume more memory and CPU.

Logging: log_level sets verbosity. Use "info" for normal operation, "debug" when troubleshooting initialization or configuration issues, and "warn" or "error" for minimal production output.

IPC Configuration: socket_path and pid_file control where the daemon creates its Unix socket and writes its process ID. The defaults work unless you're running multiple isolated instances.

Timeouts: ipc_timeout_ms determines how long to wait for operations before giving up (default: 5000ms). Increase this when working with slow providers or large model operations.

Orchestrator Configuration

The [orchestrator] section manages agent execution:

Provider Selection: default_provider determines which LLM provider is used when you don't specify one explicitly.

Task Concurrency: max_concurrent_tasks limits how many tasks a single agent executes simultaneously (typically 1 for sequential work, higher for parallel operations).

Task Timeouts: task_timeout_seconds prevents runaway operations by forcibly terminating tasks that exceed this duration (default: 300 seconds). Balance between allowing legitimate long-running work and preventing resource exhaustion.

Resource Limits

The [resources] section prevents individual agents from monopolizing system resources:

Memory: max_memory_mb caps agent memory consumption. Agents exceeding this limit get terminated. Calculate based on total RAM and concurrent agents—for 16GB RAM running 10 agents, 512MB per agent (5GB total) leaves adequate headroom.

CPU: max_cpu_percent limits CPU usage per agent. Setting this to 50 restricts each agent to half a CPU core, essential when running many agents or sharing the machine with other workloads.

Configuration Methods

Lattice supports three different ways to provide configuration values, and understanding their priority order helps you override settings effectively when needed.

The configuration file at ~/.lovelace/lattice/config.toml serves as the baseline configuration. This file is read once when the daemon starts and provides all default values. When you want to change how Lattice behaves long-term, editing this file is the right approach.

Environment variables override configuration file values and are particularly useful for providing sensitive information like API keys or for temporary configuration changes. When the daemon starts, it checks for environment variables like LATTICE_PROVIDER or LATTICE_MODEL and uses those values instead of what's in the configuration file. This lets you keep API keys out of configuration files (which might be version-controlled) while still making them available to the daemon.

Command-line flags have the highest priority and override both environment variables and the configuration file. When you start the daemon with lattice-ctl daemon start --provider anthropic --model claude-sonnet-4-6, those specific values take precedence over all other configuration. This is perfect for one-off testing or temporary changes that you don't want to persist.

The priority order from highest to lowest is: CLI flags, environment variables, configuration file, built-in defaults. This hierarchy gives you flexibility to provide baseline configuration in the file while overriding specific values through environment variables or flags when circumstances require it.

Example Configurations

Seeing complete configuration examples helps you understand how different pieces fit together. Let's look at several common setups.

For a pure local setup using Ollama, your configuration focuses on the Ollama provider and sets sensible daemon limits for local resource management:

[orchestrator]
default_provider = "ollama"

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3.2"
enabled = true

[daemon]
max_agents = 10
log_level = "info"

This configuration tells the daemon to use Ollama exclusively, connecting to the standard Ollama endpoint on localhost. With up to 10 concurrent agents allowed and info-level logging, you get a capable local AI setup with good visibility into what's happening.

For cloud-only usage with Anthropic, the configuration shifts to focus on API key management and appropriate concurrency limits:

[orchestrator]
default_provider = "anthropic"

[providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
default_model = "claude-sonnet-4-6"
enabled = true

[daemon]
max_agents = 5
log_level = "info"

Notice that max_agents is reduced to 5. When using cloud APIs, you're limited by rate limits and costs rather than local resources, so running fewer concurrent agents makes sense. The API key is referenced through an environment variable rather than hardcoded in the file, keeping credentials secure.

For hybrid setups that use both local and cloud providers, you configure multiple providers and designate one as the default:

[orchestrator]
default_provider = "ollama"

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3.2"
enabled = true

[providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
default_model = "claude-sonnet-4-6"
enabled = true

[providers.openai]
api_key_env = "OPENAI_API_KEY"
default_model = "gpt-4"
enabled = true

[daemon]
max_agents = 10
log_level = "info"

This configuration gives you maximum flexibility. Ollama serves as the default for most work, keeping costs down and data local. When you need more capable models for complex tasks, you can explicitly request Anthropic or OpenAI providers. All three providers are available simultaneously, letting you choose the right tool for each job.

Validating Your Configuration

After creating or modifying your configuration file, it's important to verify that the daemon can read it correctly and that your provider settings work as expected.

Start by restarting the daemon to load the new configuration. Remember that the daemon only reads configuration at startup, so changes don't take effect until you restart:

lattice-ctl daemon stop
lattice-ctl daemon start

Once the daemon restarts with your new configuration, verify that providers are configured as expected using lattice-ctl provider list. This shows which providers the daemon knows about and whether they're enabled. If a provider you configured doesn't appear in the list, check your configuration file for typos in provider names or TOML syntax errors.

Testing connectivity ensures your provider configurations actually work. Use lattice-ctl provider test ollama to verify the daemon can reach Ollama, or lattice-ctl provider test anthropic to check cloud provider access. These tests catch common issues like wrong base URLs, missing API keys, or network connectivity problems before you try to use the providers for real work.

Finally, check that the daemon's overall status reflects your configuration changes using lattice-ctl status. The output shows version, uptime, and current limits like max agents—verify these match what you intended.

Troubleshooting Configuration Problems

When configuration doesn't work as expected, several common issues are worth checking.

If the daemon can't find or read your configuration file, it falls back to built-in defaults. You'll notice this if your provider settings don't take effect. Verify the file exists at ~/.lovelace/lattice/config.toml and check for TOML syntax errors by viewing the file contents. Invalid TOML syntax will prevent the daemon from parsing the file, causing it to use defaults instead.

Provider configuration errors usually manifest when you try to test connectivity. If a provider doesn't appear in the list, ensure its configuration section is properly formatted and that the provider ID matches exactly. Provider IDs are case-sensitive, so "Ollama" and "ollama" are different identifiers.

Environment variable issues can be subtle because the daemon might start successfully but use unexpected values. If a provider seems configured correctly but isn't working, check that required environment variables are actually set in the daemon's environment. You can verify this by examining the daemon's startup logs in foreground mode, which shows which configuration values are being used.

Next Steps

Now that you understand how configuration works fundamentally, you can explore specific configuration scenarios in more detail. The local models guide walks through setting up Ollama and LM Studio step by step, including model selection and performance tuning for your hardware. The cloud providers guide covers obtaining API keys, managing costs, and configuring Anthropic, OpenAI, and Google providers securely.

For complete reference documentation about every available configuration option, see the config file reference. If you prefer using environment variables for configuration, the environment variables guide lists all available variables and their effects. Finally, the CLI reference shows how to use command-line flags to override configuration temporarily.