Skip to main content

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

FieldTypeDefaultDescription
namestringRequired. Unique agent identifier
createdAtstringautoISO timestamp of when this agent was created. Auto-set by addAgent()
rolestringAgent’s role description
modelstringLLM model. Format: provider:model (e.g. "anthropic:claude-sonnet-4-6") or bare model ID
allowedToolsstring[]Allowed tool names
allowedPathsstring[][workDir]Filesystem sandbox — directories the agent can access. Absolute or relative to workDir
identityAgentIdentityAgent’s identity — persona, responsibilities, communication style. See Identity
reportsTostringAgent this one reports to — org chart hierarchy for escalation. Must match another agent’s name
systemPromptstringAdditional system prompt appended to base
skillsstring[]Installed skill names (e.g. "frontend-design")
maxTurnsnumber150Max conversation turns before stopping
maxConcurrencynumberunlimitedMax concurrent tasks for this agent
volatilebooleanfalseAuto-cleanup when mission completes
missionGroupstringMission group this volatile agent belongs to
browserProfilestringagent namePersistent 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

FieldTypeDescription
displayNamestringHuman name (e.g. “Alice Chen”) — used in external communications
titlestringJob title (e.g. “Social Media Manager”)
companystringCompany name
emailstringPrimary email address (also default SMTP from)
biostringBrief persona description
timezonestringIANA timezone (e.g. “Europe/Rome”)
responsibilities(string | AgentResponsibility)[]Agent’s responsibilities — simple strings or structured objects with area, description, and priority
tonestringCommunication style — HOW the agent communicates (register, format, length)
personalitystringPersonality traits — WHO the agent IS (character, approach, values)

AgentResponsibility Fields

FieldTypeRequiredDescription
areastringyesResponsibility area (e.g. “Customer Relations”, “Content Creation”)
descriptionstringyesWhat the agent does in this area
prioritystringno"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

FieldTypeDescription
typestringRequired. One of: "smtp", "imap", "oauth", "api_key", "login", "custom"
labelstringHuman-readable label (e.g. “Work email”)
credentialsRecord<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):
  1. POLPO_VAULT_KEY environment variable
  2. ~/.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:
FieldTypeDefaultDescription
idstringautoAuto-generated unique ID
titlestringRequired. Short task title. Must be unique among active (non-terminal) tasks
descriptionstringRequired. Detailed instructions
assignTostringRequired. Agent name
groupstringMission group name
dependsOnstring[][]Task titles this depends on
statusTaskStatus"pending"Current status
expectationsExpectation[][]Assessment criteria
metricsMetric[][]Custom metrics
maxRetriesnumber3Max full retry attempts
maxDurationnumber1800000Timeout in ms (0 = no timeout)
retryPolicyRetryPolicyEscalation settings

TaskExpectation Fields

FieldTypeDescription
typestringRequired. "test", "file_exists", "script", or "llm_review"
commandstringShell command (for test and script)
pathsstring[]File paths to check (for file_exists)
criteriastringReview prompt (for llm_review)
dimensionsEvalDimension[]Scoring dimensions (for llm_review)
thresholdnumberMinimum passing score 1-5 (default: 3.0)

EvalDimension Fields

FieldTypeDescription
namestringDimension name (e.g. "correctness")
descriptionstringWhat this dimension measures
weightnumberWeight 0-1 (should sum to ~1 across dimensions)
rubricobjectScore descriptions per level (1-5)

RetryPolicy Fields

FieldTypeDescription
escalateAfternumberFailure count before escalating
fallbackAgentstringAgent for escalation retries
escalateModelstringModel override for escalation

Settings Fields

FieldTypeDefaultDescription
maxRetriesnumber3Default max retries per task
workDirstring"."Working directory
logLevelstring"normal""quiet", "normal", or "verbose"
taskTimeoutnumber1800000Default task timeout (ms)
staleThresholdnumber300000Idle time before stale warning (ms)
storagestring"file"Storage backend: "file" (filesystem JSON), "sqlite", or "postgres"
maxConcurrencynumberunlimitedMax concurrent agent processes globally
maxAssessmentRetriesnumber1Max assessment retries when all reviewers fail before falling back to fix/retry
autoCorrectExpectationsbooleantrueAuto-correct correctable expectations (e.g. file_exists paths) on assessment failure
defaultRetryPolicyRetryPolicyDefault retry policy for all tasks
enableVolatileTeamsbooleantrueAllow volatile agents in mission team: sections
volatileCleanupstring"on_complete""on_complete" or "manual"
maxFixAttemptsnumber2Max 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.
maxQuestionRoundsnumber2Max 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.
maxResolutionAttemptsnumber2Max 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.
orchestratorSkillsstring[]Skills to load into the orchestrator’s system prompt. Resolved against the orchestrator skill pool (.polpo/.agent/skills/). See Skills — Orchestrator Skills
orchestratorModelstringModel for orchestrator LLM calls
approvalGatesApprovalGate[]Approval gate checkpoints. See Approval Gates
notificationsobjectNotification routing configuration. See Notifications
escalationPolicyobjectDefault escalation chain. See Escalation
slaobjectSLA monitoring configuration. See Scoring
enableSchedulerbooleanautoEnable the scheduling engine. Default: true if any mission has a schedule
defaultQualityThresholdnumberDefault 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:
FieldTypeDescription
orgstringOrg name
judgestringModel for assessment LLM
modelstringDefault 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"
    }
  }
}
FieldTypeDescription
apiKeystringAPI key. Supports ${ENV_VAR} references resolved at startup
baseUrlstringOverride base URL (for custom proxies or self-hosted endpoints)
See Providers & Models for supported providers and model resolution.

Environment Variables

Polpo-specific

VariableDescription
POLPO_MODELGlobal default model override (e.g. anthropic:claude-sonnet-4-6)
POLPO_JUDGE_MODELModel for LLM-as-Judge assessment reviews
POLPO_STT_MODELSpeech-to-text model (default: gpt-4o-mini-transcribe)
POLPO_VAULT_KEYVault encryption key (overrides ~/.polpo/vault.key)
API_KEYServer authentication key (for HTTP API)

Provider API Keys

VariableProvider
ANTHROPIC_API_KEYAnthropic (Claude)
OPENAI_API_KEYOpenAI (GPT, o-series, DALL-E, Whisper, TTS)
GEMINI_API_KEYGoogle (Gemini)
GROQ_API_KEYGroq (Llama)
MISTRAL_API_KEYMistral
XAI_API_KEYxAI (Grok)
OPENROUTER_API_KEYOpenRouter
CEREBRAS_API_KEYCerebras
HF_TOKENHugging Face
OPENCODE_API_KEYOpenCode (free tier)
DEEPGRAM_API_KEYDeepgram (audio transcription)
ELEVENLABS_API_KEYElevenLabs (text-to-speech)
FAL_KEYfal.ai (image/video generation)
EXA_API_KEYExa AI (web search)

Extended Tool Environment Variables

VariableDescription
SMTP_HOSTSMTP host for email tools
SMTP_USERSMTP username
SMTP_PASSSMTP 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"
  }
}