Quickstart

Prerequisites

Node.js 20+ — install

1. Create and deploy a project

Run the CLI wizard from the directory that will contain your Polpo configuration:

npx @polpo-ai/cli create

The command signs you in, creates or selects an organization and project, scaffolds .polpo/, creates a project API key, writes POLPO_URL and POLPO_API_KEY to .env.local, and performs the initial deploy.

Optional: install the CLI globally

npm install -g @polpo-ai/cli

You can then run polpo create, polpo deploy, and the other commands without npx @polpo-ai/cli.

To attach an existing directory to an existing Cloud project, run npx @polpo-ai/cli link --project-id <uuid>. Linking also downloads the project’s current Polpo resources.

2. Load the generated credentials

.env.local is not loaded automatically by your shell. Load it before using the examples below:

set -a
. ./.env.local
set +a

POLPO_URL is the project data-plane URL, such as https://abcdefghijklmnopqrst.polpo.cloud.

3. Call the generated agent

The blank scaffold creates an agent named agent-1 and deploys it during create:

curl "$POLPO_URL/v1/chat/completions" \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent-1",
    "stream": false,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

The Cloud managed gateway provides model access by default. You do not need to configure a provider key for this first request.

4. Customize and redeploy

Edit .polpo/agents.json to change the generated agent. Each entry contains an agent definition and its team:

[
  {
    "agent": {
      "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."
    },
    "teamName": "default"
  }
]

Deploy the updated configuration:

npx @polpo-ai/cli deploy

See Agent Definition for the configuration fields and Deploy for deploy flags and resource behavior.

5. Use the TypeScript SDK

npm install @polpo-ai/sdk

import { PolpoClient } from "@polpo-ai/sdk";

const client = new PolpoClient({
  baseUrl: process.env.POLPO_URL!,
  apiKey: process.env.POLPO_API_KEY!,
});

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

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

For local model access and custom gateways, see Model Gateway.

Getting Started

Platform

Agents

Orchestration

Prerequisites

1. Create and deploy a project

2. Load the generated credentials

3. Call the generated agent

4. Customize and redeploy

5. Use the TypeScript SDK

​Prerequisites

​1. Create and deploy a project

​2. Load the generated credentials

​3. Call the generated agent

​4. Customize and redeploy

​5. Use the TypeScript SDK

Prerequisites

1. Create and deploy a project

2. Load the generated credentials

3. Call the generated agent

4. Customize and redeploy

5. Use the TypeScript SDK