Top-Level Structure
{
"org": "my-project",
"team": {
"name": "My Team",
"agents": []
},
"settings": {},
"providers": {}
}
Missions and tasks are stored separately in .polpo/missions/ and .polpo/tasks/ — they are not part of the config file. Use polpo mission create, the TUI, or the API to manage them.
Agent Fields
| Field | Type | Default | Description |
|---|
name | string | — | Required. Unique agent identifier |
createdAt | string | auto | ISO timestamp of when this agent was created. Auto-set by addAgent() |
role | string | — | Agent’s role description |
model | string | — | LLM model. Format: provider:model (e.g. "anthropic:claude-sonnet-4-6") or bare model ID |
allowedTools | string[] | — | Allowed tool names |
allowedPaths | string[] | [workDir] | Filesystem sandbox — directories the agent can access. Absolute or relative to workDir |
identity | AgentIdentity | — | Agent’s identity — persona, responsibilities, communication style. See Identity |
reportsTo | string | — | Agent this one reports to — org chart hierarchy for escalation. Must match another agent’s name |
systemPrompt | string | — | Additional system prompt appended to base |
skills | string[] | — | Installed skill names (e.g. "frontend-design") |
maxTurns | number | 150 | Max conversation turns before stopping |
maxConcurrency | number | unlimited | Max concurrent tasks for this agent |
volatile | boolean | false | Auto-cleanup when mission completes |
missionGroup | string | — | Mission group this volatile agent belongs to |
browserProfile | string | agent name | Persistent browser profile name. Set up via polpo browser login <agent> [url] — sessions are stored in .polpo/browser-profiles/<profileName>/. Requires browser_* in allowedTools |
HTTP tools are always-on: The http_fetch and http_download tools are included in the core tool set and available to all agents by default — no enable flag needed. Include "vault_*" in allowedTools to let agents read their own vault credentials at runtime (essential for skills that need API keys). Include "image_*" for image generation/analysis, "video_*" for video generation, "audio_*" for speech-to-text and text-to-speech, and "search_*" for web search via Exa AI. Git, multi-file, dependency management, Excel/CSV, PDF, and Word/DOCX tool categories have been removed. Use bash commands or skills for these operations instead.
AgentIdentity Fields
| Field | Type | Description |
|---|
displayName | string | Human name (e.g. “Alice Chen”) — used in external communications |
title | string | Job title (e.g. “Social Media Manager”) |
company | string | Company name |
email | string | Primary email address (also default SMTP from) |
bio | string | Brief persona description |
timezone | string | IANA timezone (e.g. “Europe/Rome”) |
responsibilities | (string | AgentResponsibility)[] | Agent’s responsibilities — simple strings or structured objects with area, description, and priority |
tone | string | Communication style — HOW the agent communicates (register, format, length) |
personality | string | Personality traits — WHO the agent IS (character, approach, values) |
AgentResponsibility Fields
| Field | Type | Required | Description |
|---|
area | string | yes | Responsibility area (e.g. “Customer Relations”, “Content Creation”) |
description | string | yes | What the agent does in this area |
priority | string | no | "critical", "high", "medium", or "low" — affects how the agent prioritizes work |
Encrypted Vault
Each agent can have its own set of credentials for different services (SMTP, IMAP, OAuth, API keys, logins). Vault entries are stored in .polpo/vault.enc, encrypted with AES-256-GCM — they are not part of polpo.json.
VaultEntry Fields
| Field | Type | Description |
|---|
type | string | Required. One of: "smtp", "imap", "oauth", "api_key", "login", "custom" |
label | string | Human-readable label (e.g. “Work email”) |
credentials | Record<string, string> | Required. Key-value credential fields. Values can reference env vars: "${ALICE_SMTP_PASS}" |
Key Management
The vault encryption key is loaded from (in order):
POLPO_VAULT_KEY environment variable
~/.polpo/vault.key — auto-generated on first use (chmod 600)
Managing Vault Entries
- CLI:
polpo agent onboard <name> — the wizard’s Email and Vault steps write to vault.enc
- TUI / Chat: Use the built-in vault tools:
set_vault_entry — add or update a credential
remove_vault_entry — delete a credential
list_vault — show all entries (credentials masked)
Vault credentials support ${ENV_VAR} syntax — at runtime, Polpo resolves them from environment variables. This keeps plaintext secrets out of the vault file entirely.
Example: Agent with Identity
{
"name": "alice",
"role": "social media manager",
"reportsTo": "marco",
"identity": {
"displayName": "Alice Chen",
"title": "Social Media Manager",
"company": "Acme Corp",
"email": "alice@acme.com",
"timezone": "Europe/Rome",
"responsibilities": [
{
"area": "Social Media Management",
"description": "Create, schedule, and publish content across all company social media platforms (Twitter, LinkedIn, Instagram). Track engagement metrics weekly.",
"priority": "high"
},
{
"area": "Customer Relations",
"description": "Monitor brand mentions and respond to customer inquiries within 2 hours. Escalate complaints to the team lead.",
"priority": "critical"
},
{
"area": "Content Calendar",
"description": "Maintain a 2-week rolling content calendar. Coordinate with the content writer for blog cross-promotion.",
"priority": "medium"
}
],
"tone": "Professional but approachable. Uses first names. Keeps emails under 3 paragraphs. Ends messages with a clear call-to-action. Uses bullet points for lists. Avoids jargon when writing to customers.",
"personality": "Empathetic and detail-oriented. Anticipates customer concerns before they escalate. Prefers data-backed decisions — always cites engagement metrics. Creative with content ideas but disciplined with deadlines. Collaborative by nature, regularly checks in with teammates."
},
"allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "ls", "browser_*", "email_*", "vault_*", "image_*", "video_*", "audio_*", "search_*"]
}
Vault entries for this agent (stored in .polpo/vault.enc) would include SMTP and IMAP credentials, managed via polpo agent onboard alice or the set_vault_entry tool.
Task Fields
Tasks are created inside missions (via CLI, TUI, or API). Each task has these fields:
| Field | Type | Default | Description |
|---|
id | string | auto | Auto-generated unique ID |
title | string | — | Required. Short task title. Must be unique among active (non-terminal) tasks |
description | string | — | Required. Detailed instructions |
assignTo | string | — | Required. Agent name |
group | string | — | Mission group name |
dependsOn | string[] | [] | Task titles this depends on |
status | TaskStatus | "pending" | Current status |
expectations | Expectation[] | [] | Assessment criteria |
metrics | Metric[] | [] | Custom metrics |
maxRetries | number | 3 | Max full retry attempts |
maxDuration | number | 1800000 | Timeout in ms (0 = no timeout) |
retryPolicy | RetryPolicy | — | Escalation settings |
TaskExpectation Fields
| Field | Type | Description |
|---|
type | string | Required. "test", "file_exists", "script", or "llm_review" |
command | string | Shell command (for test and script) |
paths | string[] | File paths to check (for file_exists) |
criteria | string | Review prompt (for llm_review) |
dimensions | EvalDimension[] | Scoring dimensions (for llm_review) |
threshold | number | Minimum passing score 1-5 (default: 3.0) |
EvalDimension Fields
| Field | Type | Description |
|---|
name | string | Dimension name (e.g. "correctness") |
description | string | What this dimension measures |
weight | number | Weight 0-1 (should sum to ~1 across dimensions) |
rubric | object | Score descriptions per level (1-5) |
RetryPolicy Fields
| Field | Type | Description |
|---|
escalateAfter | number | Failure count before escalating |
fallbackAgent | string | Agent for escalation retries |
escalateModel | string | Model override for escalation |
Settings Fields
| Field | Type | Default | Description |
|---|
maxRetries | number | 3 | Default max retries per task |
workDir | string | "." | Working directory |
logLevel | string | "normal" | "quiet", "normal", or "verbose" |
taskTimeout | number | 1800000 | Default task timeout (ms) |
staleThreshold | number | 300000 | Idle time before stale warning (ms) |
storage | string | "file" | Storage backend: "file" (filesystem JSON), "sqlite", or "postgres" |
maxConcurrency | number | unlimited | Max concurrent agent processes globally |
maxAssessmentRetries | number | 1 | Max assessment retries when all reviewers fail before falling back to fix/retry |
autoCorrectExpectations | boolean | true | Auto-correct correctable expectations (e.g. file_exists paths) on assessment failure |
defaultRetryPolicy | RetryPolicy | — | Default retry policy for all tasks |
enableVolatileTeams | boolean | true | Allow volatile agents in mission team: sections |
volatileCleanup | string | "on_complete" | "on_complete" or "manual" |
maxFixAttempts | number | 2 | Max fix attempts before full retry. During the fix phase, agents receive targeted feedback to correct specific issues instead of starting over. After maxFixAttempts fail, the task falls back to a full retry. See Escalation Chain. |
maxQuestionRounds | number | 2 | Max auto-answer rounds per task. When an agent asks a question, Polpo generates an answer using project context. After maxQuestionRounds, Q&A stops to prevent infinite loops. See Question Detection. |
maxResolutionAttempts | number | 2 | Max deadlock resolution attempts per blocked task. When a task depends on a failed dependency, Polpo evaluates whether to absorb the failure, retry the dependency, or fail the task. Each blocked task gets at most maxResolutionAttempts before being permanently failed. See Deadlock Resolution. |
orchestratorSkills | string[] | — | Skills to load into the orchestrator’s system prompt. Resolved against the orchestrator skill pool (.polpo/.agent/skills/). See Skills — Orchestrator Skills |
orchestratorModel | string | — | Model for orchestrator LLM calls |
approvalGates | ApprovalGate[] | — | Approval gate checkpoints. See Approval Gates |
notifications | object | — | Notification routing configuration. See Notifications |
escalationPolicy | object | — | Default escalation chain. See Escalation |
sla | object | — | SLA monitoring configuration. See Scoring |
enableScheduler | boolean | auto | Enable the scheduling engine. Default: true if any mission has a schedule |
defaultQualityThreshold | number | — | Default quality threshold for missions (1-5). Missions below this score are marked failed |
ProjectConfig Fields
Stored in .polpo/config.json — separate from polpo.json, this stores project-level defaults set via polpo config set:
| Field | Type | Description |
|---|
org | string | Org name |
judge | string | Model for assessment LLM |
model | string | Default model |
Providers
Per-provider API key and base URL overrides. Keys are provider names, values can be a string (shorthand for API key) or an object with apiKey and baseUrl.
{
"providers": {
"anthropic": "${ANTHROPIC_API_KEY}",
"openai": {
"apiKey": "${OPENAI_API_KEY}"
},
"openrouter": {
"apiKey": "sk-or-...",
"baseUrl": "https://openrouter.ai/api/v1"
}
}
}
| Field | Type | Description |
|---|
apiKey | string | API key. Supports ${ENV_VAR} references resolved at startup |
baseUrl | string | Override base URL (for custom proxies or self-hosted endpoints) |
See Providers & Models for supported providers and model resolution.
Environment Variables
Polpo-specific
| Variable | Description |
|---|
POLPO_MODEL | Global default model override (e.g. anthropic:claude-sonnet-4-6) |
POLPO_JUDGE_MODEL | Model for LLM-as-Judge assessment reviews |
POLPO_STT_MODEL | Speech-to-text model (default: gpt-4o-mini-transcribe) |
POLPO_VAULT_KEY | Vault encryption key (overrides ~/.polpo/vault.key) |
API_KEY | Server authentication key (for HTTP API) |
Provider API Keys
| Variable | Provider |
|---|
ANTHROPIC_API_KEY | Anthropic (Claude) |
OPENAI_API_KEY | OpenAI (GPT, o-series, DALL-E, Whisper, TTS) |
GEMINI_API_KEY | Google (Gemini) |
GROQ_API_KEY | Groq (Llama) |
MISTRAL_API_KEY | Mistral |
XAI_API_KEY | xAI (Grok) |
OPENROUTER_API_KEY | OpenRouter |
CEREBRAS_API_KEY | Cerebras |
HF_TOKEN | Hugging Face |
OPENCODE_API_KEY | OpenCode (free tier) |
DEEPGRAM_API_KEY | Deepgram (audio transcription) |
ELEVENLABS_API_KEY | ElevenLabs (text-to-speech) |
FAL_KEY | fal.ai (image/video generation) |
EXA_API_KEY | Exa AI (web search) |
| Variable | Description |
|---|
SMTP_HOST | SMTP host for email tools |
SMTP_USER | SMTP username |
SMTP_PASS | SMTP password |
Full Example
{
"org": "my-project",
"team": {
"name": "my-team",
"agents": [
{
"name": "architect",
"role": "Senior architect",
"model": "anthropic:claude-sonnet-4-6",
"maxTurns": 200,
"systemPrompt": "Always consider performance implications"
},
{
"name": "developer",
"role": "Full-stack developer",
"skills": ["frontend-design"]
},
{
"name": "script-runner",
"role": "Script executor"
}
]
},
"providers": {
"anthropic": "${ANTHROPIC_API_KEY}",
"openai": "${OPENAI_API_KEY}"
},
"settings": {
"maxRetries": 3,
"workDir": ".",
"logLevel": "normal",
"storage": "file",
"taskTimeout": 1800000,
"staleThreshold": 300000,
"maxConcurrency": 4,
"maxFixAttempts": 2,
"maxQuestionRounds": 2,
"autoCorrectExpectations": true,
"defaultQualityThreshold": 3.0,
"orchestratorModel": "claude-sonnet-4-6"
}
}