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"

# 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)
historyRetentionDays = 14   # Days to retain run history and webhook receipts (default: 14)

# Telemetry settings
[telemetry]
enabled = true
provider = "otel"
endpoint = "https://telemetry.example.com/v1"
serviceName = "action-llama"
samplingRate = 0.5

​
Field Reference

​
Top-level fields

FieldTypeDefaultDescription
maxRerunsnumber10Maximum consecutive reruns when an agent requests a rerun via al-rerun 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.
historyRetentionDaysnumber14Number of days to retain run history and webhook receipts in the local SQLite stats database. Older entries are pruned automatically.

​
[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.

​
[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.

​
[telemetry] — Observability

Optional OpenTelemetry integration.
FieldTypeDefaultDescription
enabledbooleanfalseEnable or disable telemetry collection
providerstring"none"Telemetry provider: "otel" or "none"
endpointstring—OpenTelemetry collector endpoint URL (required when provider = "otel")
serviceNamestring—Service name reported to the collector
headerstable—Additional HTTP headers sent with telemetry requests (e.g. auth tokens)
samplingRatenumber—Sampling rate between 0.0 (none) and 1.0 (all traces)

​
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.

​
VPS production (environment file)

Server configuration lives in an environment file (~/.action-llama/environments/<name>.toml), not in config.toml. See VPS Deployment for full setup. 
# ~/.action-llama/environments/production.toml
[server]
host = "5.6.7.8"
user = "root"
keyPath = "~/.ssh/id_rsa"
basePath = "/opt/action-llama"
expose = true

​
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.