Configuration Overview

Squadron uses HCL (HashiCorp Configuration Language) for all configuration.

File Structure

A typical config directory:

my-config/
├── variables.hcl    # Variable definitions
├── models.hcl       # LLM provider configurations
├── agents.hcl       # Agent definitions
├── tools.hcl        # Custom tool definitions (optional)
├── missions.hcl     # Mission definitions (optional)
└── mcp.hcl          # MCP server config (optional)

You can also put everything in a single file—Squadron reads all .hcl files in the directory.

Loading Order

Squadron uses staged evaluation to resolve references:

1. Variables - Load variable blocks (no context needed)
2. Plugins - Load plugin blocks with vars context
3. Models - Load model blocks with vars + plugins context
4. Tools - Load custom tool blocks with vars + models + plugins context
5. Agents - Load agent blocks with vars + models + tools + plugins context
6. Missions - Load mission blocks with full context

This enables expressions like:

model "anthropic" {
  api_key = vars.anthropic_api_key  # Reference a variable
}
 
agent "assistant" {
  model = models.anthropic.claude_sonnet_4  # Reference a model
  tools = [tools.weather]
}

Block Types

Block Naming

Block labels become HCL reference identifiers (e.g. models.anthropic, agents.researcher), so they must be valid identifiers. Names may contain only lowercase letters, digits, and underscores, and must not start with a digit. This applies to every named block — variable, model, agent, tool, plugin, mcp, skill, memory, mission, and mission-scoped task, dataset, and agent blocks.

agent "browser_navigator" { }   # Good
agent "agent_2" { }             # Good
 
agent "BrowserNavigator" { }    # Error — uppercase
agent "browser-navigator" { }   # Error — hyphen
agent "2nd_agent" { }           # Error — leading digit

squadron verify rejects invalid names with a pointed error.

Expressions

HCL supports expressions for dynamic values:

# String interpolation
description = "Agent for ${vars.app_name}"
 
# References
api_key = vars.anthropic_api_key
model = models.anthropic.claude_sonnet_4
 
# Lists
tools = [builtins.http.get]

Validation

Always validate your config before running:

squadron verify ./my-config

This catches errors like:

• Invalid HCL syntax
• Invalid block names (must be lowercase letters, digits, and underscores)
• Missing variable values
• Invalid model references
• Circular mission dependencies