Project Configuration

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

Field	Type	Default	Description
`maxReruns`	number	`10`	Maximum consecutive reruns before stopping
`maxCallDepth`	number	`3`	Maximum depth for agent-to-agent call chains (A calls B calls C = depth 2)
`workQueueSize`	number	`100`	Maximum 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`.
`scale`	number	(unlimited)	Project-wide cap on total concurrent runners across all agents
`resourceLockTimeout`	number	`1800`	Default lock TTL in seconds. Locks expire automatically after this duration unless refreshed via heartbeat. See Resource Locks.
`defaultWaitTimeout`	number	`1800`	Default timeout in seconds for the `wait_for_trigger` tool. Agents can override this with `waitTimeout` in their `config.toml`. See Wait & Resume.
`historyRetentionDays`	number	`14`	Number 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.

Field	Type	Default	Description
`type`	string	`"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.

Field	Type	Required	Description
`provider`	string	Yes	LLM provider: `"anthropic"`, `"openai"`, `"groq"`, `"google"`, `"xai"`, `"mistral"`, `"openrouter"`, or `"custom"`
`model`	string	Yes	Model ID (e.g. `"claude-sonnet-4-20250514"`, `"gpt-4o"`, `"gemini-2.0-flash-exp"`)
`authType`	string	Yes	Auth method: `"api_key"`, `"oauth_token"`, or `"pi_auth"`
`thinkingLevel`	string	No	Thinking 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.

Field	Type	Default	Description
`image`	string	`"al-agent:latest"`	Base Docker image name
`memory`	string	`"4g"`	Memory limit per container (e.g. `"4g"`, `"8g"`)
`cpus`	number	`2`	CPU limit per container
`timeout`	number	`900`	Default 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.

Field	Type	Default	Description
`port`	number	`8080`	Port 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.

Field	Type	Required	Description
`type`	string	Yes	Provider type: `"github"`, `"sentry"`, `"linear"`, or `"mintlify"`
`credential`	string	No	Credential 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.

First Steps

Guides

Concepts

Integrations

Reference

Full Annotated Example

Field Reference

Top-level fields

`[harness]` — Default Agent Harness

`[models.<name>]` — Named Models

`[local]` — Docker Container Settings

`[gateway]` — HTTP Server

`[webhooks.*]` — Webhook Sources

Minimal Examples

Anthropic with Docker (typical dev setup)

Cloud Run Jobs runtime (environment file)

​Full Annotated Example

​Field Reference

​Top-level fields

​[harness] — Default Agent Harness

​[models.<name>] — Named Models

​[local] — Docker Container Settings

​[gateway] — HTTP Server

​[webhooks.*] — Webhook Sources

​Minimal Examples

​Anthropic with Docker (typical dev setup)

​Cloud Run Jobs runtime (environment file)

Full Annotated Example

Field Reference

Top-level fields

`[harness]` — Default Agent Harness

`[models.<name>]` — Named Models

`[local]` — Docker Container Settings

`[gateway]` — HTTP Server

`[webhooks.*]` — Webhook Sources

Minimal Examples

Anthropic with Docker (typical dev setup)

Cloud Run Jobs runtime (environment file)