Documentation Index
Fetch the complete documentation index at: https://docs.actionllama.org/llms.txt
Use this file to discover all available pages before exploring further.
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"
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"
config.toml:
# agents/<name>/config.toml
models = ["sonnet", "haiku"]
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
config.toml:
# agents/<name>/config.toml
[[webhooks]]
source = "my-github"
events = ["issues"]
Minimal Examples
Anthropic with Docker (typical dev setup)
[models.sonnet]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
thinkingLevel = "medium"
authType = "api_key"
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