Skip to main content
The project-level config.toml lives at the root of your Action Llama project. All sections and fields are optional — sensible defaults are used for anything you omit. If the file doesn’t exist at all, an empty config is assumed.

​
Full Annotated Example

# Named models — define once, reference by name in SKILL.md
[models.sonnet]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
thinkingLevel = "medium"
authType = "api_key"

[models.haiku]
provider = "anthropic"
model = "claude-haiku-4-5-20251001"
authType = "api_key"

[models.gpt4o]
provider = "openai"
model = "gpt-4o"
authType = "api_key"

# Default harness for all agents unless overridden per-agent
[harness]
type = "pi"                  # "pi" (default) or "claude"

# Local Docker container settings
[local]
image = "al-agent:latest"   # Base image name (default: "al-agent:latest")
memory = "4g"               # Memory limit per container (default: "4g")
cpus = 2                    # CPU limit per container (default: 2)
timeout = 900               # Default max container runtime in seconds (default: 900, overridable per-agent)

# Gateway HTTP server settings
[gateway]
port = 8080                 # Gateway port (default: 8080)

# Webhook sources — named webhook endpoints with provider type and credential
[webhooks.my-github]
type = "github"
credential = "MyOrg"              # credential instance for HMAC validation

# Scheduler settings
resourceLockTimeout = 1800  # Lock TTL in seconds (default: 1800 / 30 minutes)
maxReruns = 10              # Max consecutive reruns for successful agent runs (default: 10)
maxCallDepth = 3            # Max depth for agent-to-agent call chains (default: 3)
workQueueSize = 100         # Max queued work items (webhooks + calls) per agent (default: 100)
scale = 10                  # Project-wide max concurrent runners across all agents (default: unlimited)
defaultWaitTimeout = 1800   # Default timeout for wait_for_trigger in seconds (default: 1800 / 30 min)
historyRetentionDays = 14   # Days to retain run history and webhook receipts (default: 14)

​
Field Reference

​
Top-level fields

FieldTypeDefaultDescription
maxRerunsnumber10Maximum consecutive reruns before stopping
maxCallDepthnumber3Maximum depth for agent-to-agent call chains (A calls B calls C = depth 2)
workQueueSizenumber100Maximum queued work items (webhook events + agent calls) per agent when all runners are busy. Can be overridden per-agent with maxWorkQueueSize in the agent’s config.toml.
scalenumber(unlimited)Project-wide cap on total concurrent runners across all agents
resourceLockTimeoutnumber1800Default lock TTL in seconds. Locks expire automatically after this duration unless refreshed via heartbeat. See Resource Locks.
defaultWaitTimeoutnumber1800Default timeout in seconds for the wait_for_trigger tool. Agents can override this with waitTimeout in their config.toml. See Wait & Resume.
historyRetentionDaysnumber14Number of days to retain run history and webhook receipts in the local SQLite stats database. Older entries are pruned automatically.

​
[harness] — Default Agent Harness

Selects the default harness used to execute agents. This can be overridden per-agent in agents/<name>/config.toml.
FieldTypeDefaultDescription
typestring"pi"Harness type: "pi" or "claude"
[harness]
type = "claude"
Use pi for the default multi-provider runtime with model fallback chains. Use claude to run the agent through the Claude CLI harness instead. The claude harness uses the agent’s primary model only, so any additional models listed for fallback are ignored.

​
[models.<name>] — Named Models

Define models once in config.toml, then reference them by name in each agent’s SKILL.md frontmatter. Agents list model names in priority order — the first is the primary model, and the rest are fallbacks tried automatically when the primary is rate-limited or unavailable.
FieldTypeRequiredDescription
providerstringYesLLM provider: "anthropic", "openai", "groq", "google", "xai", "mistral", "openrouter", or "custom"
modelstringYesModel ID (e.g. "claude-sonnet-4-20250514", "gpt-4o", "gemini-2.0-flash-exp")
authTypestringYesAuth method: "api_key", "oauth_token", or "pi_auth"
thinkingLevelstringNoThinking budget: "off", "minimal", "low", "medium", "high", "xhigh". Only applies to Anthropic models with reasoning support. Ignored for other providers.
[models.sonnet]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
thinkingLevel = "medium"
authType = "api_key"

[models.haiku]
provider = "anthropic"
model = "claude-haiku-4-5-20251001"
authType = "api_key"

[models.gpt4o]
provider = "openai"
model = "gpt-4o"
authType = "api_key"
Agents reference these by name in their config.toml: 
# agents/<name>/config.toml
models = ["sonnet", "haiku"]
See Models for all supported providers, model IDs, auth types, and thinking levels. When using the claude harness, configure the agent’s primary model as an Anthropic Claude model. The Claude CLI harness runs that first model directly rather than using the full fallback chain.

​
[local] — Docker Container Settings

Controls local Docker container isolation. These settings apply only to agents using the default container runtime — they are ignored for agents using the host-user runtime.
FieldTypeDefaultDescription
imagestring"al-agent:latest"Base Docker image name
memorystring"4g"Memory limit per container (e.g. "4g", "8g")
cpusnumber2CPU limit per container
timeoutnumber900Default max container runtime in seconds. Individual agents can override this with timeout in their config.toml. See agent timeout.

​
[gateway] — HTTP Server

The gateway starts automatically when Docker mode or webhooks are enabled. It handles health checks, webhook reception, credential serving (local Docker only), resource locking, and the shutdown kill switch.
FieldTypeDefaultDescription
portnumber8080Port for the gateway HTTP server

​
[webhooks.*] — Webhook Sources

Named webhook sources that agents can reference in their webhook triggers. Each source defines a provider type and an optional credential for signature validation.
FieldTypeRequiredDescription
typestringYesProvider type: "github", "sentry", "linear", or "mintlify"
credentialstringNoCredential instance name for HMAC signature validation (e.g. "MyOrg" maps to github_webhook_secret:MyOrg). Omit for unsigned webhooks.
[webhooks.my-github]
type = "github"
credential = "MyOrg"              # uses github_webhook_secret:MyOrg for HMAC validation

[webhooks.my-sentry]
type = "sentry"
credential = "SentryProd"         # uses sentry_client_secret:SentryProd

[webhooks.my-linear]
type = "linear"
credential = "LinearMain"         # uses linear_webhook_secret:LinearMain

[webhooks.my-mintlify]
type = "mintlify"
credential = "MintlifyMain"       # uses mintlify_webhook_secret:MintlifyMain

[webhooks.unsigned-github]
type = "github"                   # no credential — accepts unsigned webhooks
Agents reference these sources by name in their config.toml: 
# agents/<name>/config.toml
[[webhooks]]
source = "my-github"
events = ["issues"]
See Webhooks for setup instructions and filter fields per provider.

​
Minimal Examples

​
Anthropic with Docker (typical dev setup)

[models.sonnet]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
thinkingLevel = "medium"
authType = "api_key"
Everything else uses defaults: Docker enabled, 4GB memory, 2 CPUs, 15min timeout, gateway on port 8080.

​
Cloud Run Jobs runtime (environment file)

To run agents as Cloud Run Jobs instead of local Docker containers, add a [cloud] section to your environment file. The scheduler still runs wherever you host it; only agent execution is offloaded to GCP. 
# ~/.action-llama/environments/production.toml
[cloud]
provider = "cloud-run"
project = "my-gcp-project"
region = "us-central1"
artifact_registry = "al-agents"
# Optional: service account email for job execution identity
# service_account = "[email protected]"

[gateway]
url = "https://your-gateway.example.com"  # Must be publicly reachable
See Running Agents on Cloud Run Jobs for full setup instructions.