Configuration

AgentLoop reads YAML configuration files with a layered priority system. This page documents the most commonly used options.

Most settings can also be edited from the Configuration panel inside the desktop app — but if you’d rather edit the YAML directly, the file paths and options below are the source of truth.

Configuration File Locations

Configuration Priority

Settings are applied in this order (highest priority first):

1. Environment variables (where supported)
2. Project config (./.agentloop/config.yaml)
3. User config (~/.config/agentloop/config.yaml)
4. Built-in defaults

When the same key appears in both files, the project value wins. Sections that don’t conflict are merged, so user-level defaults stay in effect for anything the project config doesn’t override.

Editing Configuration

The easiest way to edit configuration is from the Configuration panel in the desktop app — it gives you a guided UI with descriptions and validation, and writes the same YAML files described here.

If you prefer to edit YAML directly, restart the daemon (or quit and reopen the desktop app) so the new values take effect.

Top-Level Keys

A config file is a single YAML document. The following top-level keys are recognized:

You only need to include the keys you want to set. Anything you omit falls back to defaults.

Model Settings

The models key holds your default model and recently used models. The default model is Claude Opus 4.8 (anthropic/claude-opus-4-8).

models:
  default: "anthropic/claude-opus-4-8"   # Model used for new work

To use Claude models you can either sign in with a Claude Pro or Max subscription (“Use Claude subscription”) or provide an Anthropic API key (see Anthropic Settings). Both options are supported; the subscription option is the simplest if you don’t have an API key.

Orchestrator Settings

orchestrator:
  max_parallel_agents: 4               # Total agent slots (minimum 4)
  worktrees_dir: ".worktrees"          # Where per-task git worktrees are created
  cleanup_worktrees_on_complete: false # Auto-cleanup worktrees after completion
  base_branch: "main"                  # Base branch for worktrees and PRs
  sync_agents: none                    # Which built-in agents to copy into the project

There are additional knobs for QA bounce limits, trigger retries, and merge-resolver scope. The defaults are sensible for most projects; the desktop Configuration panel exposes them with inline help when you need to tune them.

Container Sandbox Settings

Container sandboxing isolates each agent in its own Podman or Docker container.

orchestrator:
  container_sandbox:
    enabled: false
    runtime: "auto"                # auto, podman, or docker
    container_image: "agentloop-worker"
    network_mode: "slirp4netns"    # none, slirp4netns, or host
    memory_limit: "4g"
    cpu_limit: "2"
    agent_images:
      engineer: "agentloop-worker"
      qa-tester: "agentloop-qa-worker"

See Container Sandboxing for details on building images and choosing a runtime.

GitHub Settings

github:
  enabled: true
  token: "ghp_your_token_here"   # Or set GITHUB_PERSONAL_ACCESS_TOKEN

Anthropic Settings

These settings apply when you bring your own Anthropic API key. If you’d rather not manage a key, you can instead sign in with a Claude Pro or Max subscription from the account menu — no anthropic block required.

anthropic:
  api_key: "sk-ant-..."          # Or set ANTHROPIC_API_KEY
  base_url: "https://api.anthropic.com"  # Optional override

Jira Settings

Jira accepts either OAuth credentials or a Basic Auth email + API token.

jira:
  siteUrl: "https://yourcompany.atlassian.net"
  project: "PROJ"
 
  # OAuth (recommended)
  clientId: "your_client_id"
  clientSecret: "your_client_secret"
 
  # Basic Auth (simpler, less secure)
  email: "user@example.com"
  apiToken: "your_api_token"

See Integrations for full Jira setup.

Hooks

The hooks: block lets you run shell commands when AgentLoop events fire (task status changes, agent completions, orchestrator lifecycle, etc.). Hook configuration lives in the same file as the rest of your settings.

See the dedicated Hooks page for events, payloads, matchers, and examples.

Example Configurations

User-Level Defaults

~/.config/agentloop/config.yaml:

github:
  enabled: true
 
orchestrator:
  max_parallel_agents: 4
  cleanup_worktrees_on_complete: false

Project-Level Overrides

./.agentloop/config.yaml:

orchestrator:
  max_parallel_agents: 10
  base_branch: "main"
  container_sandbox:
    enabled: true
    network_mode: "slirp4netns"
 
jira:
  siteUrl: "https://company.atlassian.net"
  project: "MYPROJ"

Minimal Configuration

github:
  enabled: true

Full Configuration

A representative config showing the most commonly tweaked options:

# GitHub integration
github:
  enabled: true
 
# Orchestrator settings
orchestrator:
  max_parallel_agents: 4
  worktrees_dir: ".worktrees"
  cleanup_worktrees_on_complete: false
  base_branch: "main"
  sync_agents: none
 
  # Container sandboxing
  container_sandbox:
    enabled: true
    runtime: "auto"
    container_image: "agentloop-worker"
    network_mode: "slirp4netns"
    memory_limit: "8g"
    cpu_limit: "4"
    agent_images:
      engineer: "agentloop-worker"
      qa-tester: "agentloop-qa-worker"
 
# Jira integration
jira:
  siteUrl: "https://company.atlassian.net"
  project: "DEV"
  email: "developer@company.com"
  apiToken: "your-jira-api-token"

Environment Variables

Many settings can be overridden with environment variables, which take precedence over both YAML files:

# Orchestrator
export AGENTLOOP_MAX_PARALLEL_AGENTS=4
export AGENTLOOP_WORKTREES_DIR=".worktrees"
export AGENTLOOP_CLEANUP_WORKTREES=false
export AGENTLOOP_BASE_BRANCH="main"
 
# GitHub
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_..."
 
# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

Security Best Practices

• Prefer environment variables (or your OS credential store) for tokens and secrets
• Add .agentloop/config.yaml to .gitignore if it contains credentials
• Use OAuth for Jira instead of Basic Auth when possible
• Rotate API tokens regularly

Example .gitignore:

.agentloop/config.yaml
.agentloop/credentials/