Skip to main content
The .polpo/polpo.json file defines project settings, LLM gateway configuration, and provider overrides.

​
PolpoConfig

interface PolpoFileConfig {
  project: string;
  settings: PolpoSettings;
  providers?: Record<string, ProviderConfig>;
}

​
Settings

interface PolpoSettings {

  maxRetries: number;
  workDir: string;
  logLevel: "quiet" | "normal" | "verbose";
  storage?: "file" | "sqlite" | "postgres";
  databaseUrl?: string;
  gateway?: {
    url: string;
    headers?: Record<string, string>;
  };


  taskTimeout?: number;
  staleThreshold?: number;
  maxConcurrency?: number;
  maxFixAttempts?: number;
  maxQuestionRounds?: number;
  maxResolutionAttempts?: number;
  maxAssessmentRetries?: number;


  orchestratorModel?: string | {
    primary?: string;
    fallbacks?: string[];
  };
  imageModel?: string;
  reasoning?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
  modelAllowlist?: Record<string, {
    alias?: string;
    params?: Record<string, unknown>;
  }>;


  enableVolatileTeams?: boolean;
  volatileCleanup?: "on_complete" | "manual";
  autoCorrectExpectations?: boolean;
  enableScheduler?: boolean;
  defaultQualityThreshold?: number;
  orchestratorSkills?: string[];


  defaultRetryPolicy?: RetryPolicy;
  approvalGates?: ApprovalGate[];
  escalationPolicy?: EscalationPolicy;
  sla?: SLAConfig;
  emailAllowedDomains?: string[];
}

​
Providers

Override LLM provider endpoints and add custom models: 
interface ProviderConfig {
  baseUrl?: string;
  api?: "openai-completions" | "openai-responses" | "anthropic-messages";
  models?: CustomModelDef[];
}

interface CustomModelDef {
  id: string;
  name: string;
  reasoning?: boolean;
  input?: ("text" | "image")[];
  contextWindow?: number;
  maxTokens?: number;
  cost?: {
    input: number;
    output: number;
    cacheRead: number;
    cacheWrite: number;
  };
}

​
Retry policy

interface RetryPolicy {
  escalateAfter?: number;
  fallbackAgent?: string;
  escalateModel?: string;
}

​
SLA

interface SLAConfig {
  warningThreshold?: number;
  checkIntervalMs?: number;
  warningChannels?: string[];
  violationChannels?: string[];
  violationAction?: "notify" | "fail";
}

​
Example

{
  "project": "my-app",
  "settings": {
    "maxRetries": 2,
    "workDir": ".",
    "logLevel": "normal",
    "storage": "file",
    "reasoning": "medium",
    "orchestratorModel": "anthropic/claude-sonnet-4-5",
    "gateway": {
      "url": "https://ai-gateway.vercel.sh/v1"
    }
  },
  "providers": {
    "openrouter": {
      "models": [
        {
          "id": "minimax/minimax-m2.7",
          "name": "MiniMax M2.7",
          "contextWindow": 196000,
          "maxTokens": 16384
        }
      ]
    }
  }
}
The gateway setting routes all LLM calls through a single endpoint. If omitted, Polpo uses direct provider API keys. On Polpo Cloud, the managed gateway is active by default. See LLM Configuration for details.