Polpo is configured through a JSON file at .polpo/polpo.json in your project directory. Run polpo init to create one with defaults.
File Structure
{
"org": "my-project",
"team": {
"name": "default",
"description": "Project team description",
"agents": [
{
"name": "agent-name",
"role": "Role description",
"model": "anthropic:claude-sonnet-4-6"
}
]
},
"providers": {
"anthropic": "${ANTHROPIC_API_KEY}",
"openai": "${OPENAI_API_KEY}"
},
"settings": {
"maxRetries": 3,
"workDir": ".",
"logLevel": "normal"
}
}
Missions and tasks are managed dynamically via the TUI, CLI, or API. They are stored separately in .polpo/missions/ and .polpo/tasks/ — not in the config file.
Agents
Each agent entry defines a worker that can be assigned tasks. You specify a name, a role describing its expertise, and optionally a model for the LLM to use.
{
"team": {
"agents": [
{
"name": "developer",
"model": "anthropic:claude-sonnet-4-6",
"role": "Full-stack developer"
},
{
"name": "architect",
"model": "anthropic:claude-sonnet-4-6",
"role": "Senior software architect who designs system components"
}
]
}
}
allowedTools (include "browser_*", "email_*", "vault_*", "image_*", "video_*", "audio_*", or "search_*" for extended tools), allowedPaths, skills, and more. See Configuration Reference for the full field list.
Creating Missions
Missions are created via the CLI or TUI — not by editing the config file:
# AI-generated mission from a prompt
polpo mission create "Build a REST API with auth and tests"
# List and inspect missions
polpo mission list
polpo mission show <mission-id>
# Execute a mission
polpo mission execute <mission-id>
The TUI mission command lets you create missions from templates or generate them with AI. # Create a mission
curl -X POST http://localhost:3000/api/v1/projects/my-project/missions \
-H "Content-Type: application/json" \
-d '{"prompt": "Build a REST API with auth"}'
# Execute a mission
curl -X POST http://localhost:3000/api/v1/projects/my-project/missions/<mission-id>/execute
| Field | Type | Description |
|---|
title | string | Short task title |
description | string | Detailed instructions |
assignTo | string | Agent name from your team |
dependsOn | string[] | Titles of tasks that must finish first |
expectations | array | Assessment criteria |
Settings
The settings object controls Polpo’s behavior — retry limits, tick interval, log level, stale detection thresholds, and more:
{
"settings": {
"maxRetries": 3,
"maxFixAttempts": 2,
"staleThreshold": 300000,
"logLevel": "normal",
"workDir": ".",
"orchestratorModel": "claude-sonnet-4-6"
}
}
Optional Systems
Polpo has several optional capabilities that can be enabled in the config:
| System | Config Key | Learn More |
|---|
| Approval gates | approvalGates | Approval Gates |
| Notifications | notifications | Notifications |
| Escalation | escalationPolicy | Escalation Chain |
| SLA monitoring | sla | Scoring |
| Scheduling | enableScheduler | Scheduling |
| Quality threshold | defaultQualityThreshold | Scoring |
Environment Variables
# Optional: use a specific provider
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
# Optional: customize orchestrator LLM
POLPO_MODEL=anthropic:claude-sonnet-4-6
POLPO_JUDGE_MODEL=anthropic:claude-sonnet-4-6
# Optional: server authentication
API_KEY=your-secret-key
Config Path
By default, Polpo looks for .polpo/polpo.json in the current directory. Use -d or --dir to specify a different working directory:
polpo run -d /path/to/workdir
polpo -d /path/to/workdir
