Skip to main content

​
Prerequisites

  • Node.js 20+ — install
  • An LLM API key (Anthropic, OpenAI, Google, xAI, OpenRouter, etc.)

​
1. Install

npm install -g polpo-ai

​
2. Define your agent

Create .polpo/agents.json: 
[
  {
    "name": "backend-dev",
    "role": "Senior backend engineer",
    "model": "anthropic:claude-sonnet-4-5",
    "allowedTools": ["read", "write", "edit", "bash", "glob", "grep"],
    "systemPrompt": "Write clean, tested TypeScript."
  }
]
Or let your coding agent do it — install the Polpo skills first: 
npx skills add lumea-labs/polpo-skills
Then ask your agent: 
> Create a Polpo agent for backend development with Claude Sonnet
See Definition for all available fields.

​
3. Set your LLM key

polpo byok set anthropic
Or set it as an environment variable: 
export ANTHROPIC_API_KEY=sk-ant-...
The deploy will detect local keys and offer to push them to the cloud. See LLM Provider Keys for all supported providers.
Want to develop locally instead of deploying? Run polpo start — no account needed. See Local Development.

​
4. Login

​
5. Deploy

polpo deploy
See Deploy for more details.

​
6. Call your agent

curl https://api.polpo.sh/v1/chat/completions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "backend-dev",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'
Or use the SDK: 
import { PolpoClient } from "@polpo-ai/sdk";

const client = new PolpoClient({
  baseUrl: "https://api.polpo.sh",
  apiKey: "sk_live_...",
});

const stream = client.chatCompletionsStream({
  agent: "backend-dev",
  messages: [{ role: "user", content: "Hello" }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
Want to develop locally first? Run polpo start — no account needed. See Local Development.