agent-config.toml Reference
Each agent has anagent-config.toml file in its directory. The agent name is derived from the directory name and should not be included in the config.
Full Annotated Example
Field Reference
| Field | Type | Required | Description |
|---|---|---|---|
credentials | string[] | Yes | Credential refs: "type" for default instance, "type:instance" for named instance |
schedule | string | No* | Cron expression for polling |
scale | number | No | Number of concurrent runs allowed (default: 1). Set to 0 to disable the agent. Use lock skills in your actions to coordinate instances. See Resource Locks. |
timeout | number | No | Max runtime in seconds. Falls back to [local].timeout in project config, then 900. On AWS ECS, agents with timeout ≤ 900 auto-route to Lambda for faster startup. See Timeout. |
model | table | No | LLM model configuration (falls back to [model] in project config.toml) |
model.provider | string | Yes* | LLM provider (“anthropic”, “openai”, “groq”, “google”, “xai”, “mistral”, “openrouter”, or “custom”) |
model.model | string | Yes* | Model ID |
model.thinkingLevel | string | No | Thinking budget level: off, minimal, low, medium, high, xhigh. Only relevant for Claude Sonnet/Opus. Omit for other models. |
model.authType | string | Yes* | Auth method for the provider |
webhooks | array | No* | Array of webhook trigger objects |
preflight | array | No | Array of preflight steps that run before the LLM session. See Preflight. |
params | table | No | Custom key-value params for the agent prompt |
schedule or webhooks is required (unless scale = 0). *Required within [model] if the agent defines its own model block (otherwise inherits from project config.toml).
Scale
Thescale field controls how many instances of an agent can run concurrently. This is useful for agents that handle high-volume workloads or when you want to process multiple tasks simultaneously.
- Default: 1 (only one instance can run at a time)
- Minimum: 0 (disables the agent — no runners, cron jobs, or webhook bindings are created)
- Maximum: No hard limit, but consider system resources and model API rate limits
How it works
- Scheduled runs: If a cron trigger fires but all agent instances are busy, the scheduled run is skipped with a warning
- Webhook events: If a webhook arrives but all instances are busy, the event is queued (up to
workQueueSizelimit in global config, default: 100) - Agent calls: If one agent calls another but all target instances are busy, the call is queued in the same work queue and processed when a runner frees up
Example use cases
- Dev agent with
scale = 3: Handle multiple GitHub issues simultaneously - Review agent with
scale = 2: Review multiple PRs in parallel - Monitoring agent with
scale = 1: Ensure only one instance processes alerts at a time - Disabled agent with
scale = 0: Keep the config in the project but don’t run it
Resource considerations
Each parallel instance:- Uses separate Docker containers (in Docker mode)
- Has independent logging streams
- May consume LLM API quota concurrently
- Uses system memory and CPU
Timeout
Thetimeout field controls the maximum runtime for an agent invocation. When the timeout expires, the container is terminated.
Resolution order: agent-config.toml timeout -> config.toml [local].timeout -> 900 (default)
This means you can set a project-wide default in [local].timeout and override it per-agent.
Automatic Lambda routing (AWS ECS)
When usingcloud.provider = "ecs", agents are automatically routed to the most efficient AWS compute service based on their effective timeout:
| Effective timeout | Runtime | Cold start | Cost |
|---|---|---|---|
| ≤ 900s (15 min) | AWS Lambda | ~1-2s | Lower (pay per 100ms) |
| > 900s | ECS Fargate | ~30-60s | Higher (pay per second, 1-min minimum) |
timeout = 600 or similar. The agent gets faster startup and lower cost on AWS. If an agent needs more than 15 minutes (e.g., large refactoring tasks, long-running monitoring loops), use a longer timeout and it will route to ECS Fargate automatically.
Lambda IAM roles
Whenal doctor -c runs, it automatically creates Lambda execution roles (al-{agentName}-lambda-role) for agents whose effective timeout is ≤ 900s. These roles include permissions for Secrets Manager access, CloudWatch Logs, and ECR image pull. You can override the role with cloud.lambdaRoleArn in config.toml.
Examples
Preflight
Preflight steps run mechanical data-staging tasks after credentials are loaded but before the LLM session starts. They fetch data, clone repos, or run commands to prepare the workspace so the agent starts with everything it needs — instead of spending tokens fetching context at runtime.How it works
- Steps run sequentially in the order they appear in
agent-config.toml - Steps run inside the container (or host process in
--no-dockermode) after credential/env setup - Providers write files to disk — your ACTIONS.md references the staged files
- Environment variable interpolation is supported:
${VAR_NAME}in string params is resolved againstprocess.env(which already has credentials injected)
Step fields
Each[[preflight]] entry has these fields:
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Provider name: shell, http, or git-clone |
required | boolean | No | If true (default), the agent aborts on failure. If false, logs a warning and continues. |
params | table | Yes | Provider-specific parameters (see below) |
Built-in providers
shell
Runs a command via /bin/sh. Optionally captures stdout to a file.
| Param | Type | Required | Description |
|---|---|---|---|
command | string | Yes | Shell command to execute |
output | string | No | File path to write stdout to. Parent directories are created automatically. |
http
Fetches a URL and writes the response body to a file.
| Param | Type | Required | Description |
|---|---|---|---|
url | string | Yes | URL to fetch |
output | string | Yes | File path to write the response body |
method | string | No | HTTP method (default: GET) |
headers | table | No | HTTP headers as key-value pairs |
body | string | No | Request body (for POST/PUT) |
git-clone
Clones a git repository. Short "owner/repo" names are expanded to [email protected]:owner/repo.git; full URLs are passed through. Git credentials (SSH key, HTTPS token) are already configured from the agent’s credentials.
| Param | Type | Required | Description |
|---|---|---|---|
repo | string | Yes | Repository: "owner/repo" or full URL |
dest | string | Yes | Local path to clone into |
branch | string | No | Branch to check out |
depth | number | No | Shallow clone depth (e.g., 1) |
Referencing staged files in ACTIONS.md
Preflight writes files to disk — your ACTIONS.md tells the LLM what’s there:Notes
- The
shellprovider is the escape hatch — anything a built-in provider doesn’t cover can be expressed as a shell command - There is no per-step timeout — steps are bounded by the container-level timeout
- Environment variables set inside
shellchild processes do not propagate back to the agent’sprocess.env
Webhook Trigger Fields
Each[[webhooks]] entry has the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | Name of a webhook source from the project’s config.toml (e.g. "my-github") |
GitHub filter fields
| Field | Type | Description |
|---|---|---|
repos | string[] | Filter to specific repos |
events | string[] | Event types: issues, pull_request, push, etc. |
actions | string[] | Event actions: opened, labeled, closed, etc. |
labels | string[] | Only trigger when issue/PR has these labels |
assignee | string | Only trigger when assigned to this user |
author | string | Only trigger for this author |
branches | string[] | Only trigger for these branches |
Sentry filter fields
| Field | Type | Description |
|---|---|---|
resources | string[] | Resource types: event_alert, metric_alert, issue, error, comment |
Model Configuration
The[model] section is optional — agents inherit the default model from the project’s config.toml. Only add [model] to an agent config if you want to override the default for that specific agent.
See Models for all supported providers, model IDs, auth types, thinking levels, and credential setup.
Cloud Runtimes
Cloud Run (GCP)
When using Cloud Run mode (cloud.provider = "cloud-run" in config.toml), each agent automatically gets a per-agent service account (al-{agentName}@{gcpProject}.iam.gserviceaccount.com) that only has access to the credentials listed in that agent’s credentials array. Run al doctor -c to create the service accounts and IAM bindings. See Cloud Run docs for details.
ECS Fargate (AWS)
When using ECS mode (cloud.provider = "ecs" in config.toml), each agent automatically uses a per-agent IAM task role (al-{agentName}-task-role) that only has access to the credentials listed in that agent’s credentials array. The task role ARN is derived from the ECR repository’s account ID. See ECS docs for setup instructions including how to create the per-agent task roles.