Skip to main content

​
Prerequisites

​
1. Create a project

One command — handles login, project creation, agent scaffolding, and API key generation: 
npx @polpo-ai/cli create
For shorter commands (polpo deploy instead of npx @polpo-ai/cli deploy):
npm install -g @polpo-ai/cli
This creates a .polpo/ directory with your agent config, links it to a cloud project, and generates credentials.
Already have a cloud project? Use polpo link --project-id <uuid> to bind your local directory to it instead.

​
3. Define your agent

Edit .polpo/agents.json — each entry wraps an agent config with its team: 
[
  {
    "agent": {
      "name": "backend-dev",
      "role": "Senior backend engineer",
      "model": "anthropic/claude-sonnet-4",
      "allowedTools": ["read", "write", "edit", "bash", "glob", "grep"],
      "systemPrompt": "Write clean, tested TypeScript."
    },
    "teamName": "default"
  }
]
Or let your coding agent do it — install the Polpo skills first: 
npx @polpo-ai/cli install --client claude-code
Then ask your agent: 
> Create a Polpo agent for backend development with Claude Sonnet
See Definition for all available fields.

​
4. LLM access

On Polpo Cloud, the managed AI Gateway is enabled by default — no API key setup needed. Deploy your agents and they work immediately with 20+ LLM providers. For local development, set the provider API key as an environment variable: 
export ANTHROPIC_API_KEY=sk-ant-...
Or configure providers in your .polpo/polpo.json: 
{
  "settings": {
    "providers": {
      "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" }
    }
  }
}
See LLM Configuration for gateway setup and all supported providers.

​
5. Deploy

polpo deploy
This validates your .polpo/ config and pushes it to the cloud. Your agents are live at {project}.polpo.cloud. See Deploy for more details.

​
6. Call your agent

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

const client = new PolpoClient({
  baseUrl: "https://{project}.polpo.cloud",
  apiKey: process.env.POLPO_API_KEY!,
});

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

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}