Local Development

The open-source server runs without a Polpo Cloud account. The repository requires Node.js 20+ and pnpm through Corepack.

Build the server

git clone https://github.com/lumea-labs/polpo.git
cd polpo
corepack enable
pnpm install --frozen-lockfile
pnpm build

The root pnpm dev script only watches TypeScript; it does not start an HTTP server.

Create a local project

The server reads a project from WORK_DIR. Create a workspace with these files:

workspace/
└── .polpo/
    ├── polpo.json
    ├── teams.json
    └── agents.json

.polpo/polpo.json

{
  "project": "local-project",
  "settings": {
    "storage": "file"
  }
}

.polpo/teams.json

[
  {
    "name": "default",
    "description": "Default team"
  }
]

.polpo/agents.json

[
  {
    "agent": {
      "name": "agent-1",
      "role": "Helpful assistant",
      "model": "anthropic/claude-sonnet-4-5",
      "allowedTools": ["read", "write", "edit", "bash", "glob", "grep"]
    },
    "teamName": "default"
  }
]

Start the server

From the cloned Polpo repository:

export WORK_DIR="$PWD/workspace"
export ANTHROPIC_API_KEY=sk-ant-...
node bin/polpo-server.mjs

The server listens on http://localhost:3890 by default. Provider credentials can also go in workspace/.polpo/.env. Check the server:

curl http://localhost:3890/api/v1/health

Call chat completions at the OpenAI-compatible path:

curl http://localhost:3890/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent-1",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Use the SDK

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

const client = new PolpoClient({
  baseUrl: "http://localhost:3890",
});

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

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

Authentication is disabled when both POLPO_API_KEY and POLPO_API_KEYS are unset. See Self-hosting before exposing the server to a network.

Run the dashboard locally

The open-source repository includes a single-tenant Next.js host for the v2 runtime views. In a second terminal:

POLPO_API_URL=http://127.0.0.1:3890 \
POLPO_API_KEY="$POLPO_API_KEY" \
pnpm --filter @polpo-ai/dashboard-app dev

Open http://localhost:3000. The app proxies requests server-side, so the runtime API key is not embedded in the browser bundle. The reusable views are published separately as @polpo-ai/dashboard for custom hosts.

Move the configuration to Cloud

From the project workspace, authenticate and deploy. When the local config has no Cloud project ID, the deploy command resolves or creates the target project interactively:

polpo login
polpo deploy

Use polpo link --project-id <uuid> only when you intend to bind to an existing project and pull its current remote resources before deploying. The CLI can offer to upload recognized local provider keys during deploy. See Deploy and Model Gateway.

Getting Started

Platform

Agents

Orchestration

Local Development

Build the server

Create a local project

Start the server

Use the SDK

Run the dashboard locally

Move the configuration to Cloud

​Build the server

​Create a local project

​Start the server

​Use the SDK

​Run the dashboard locally

​Move the configuration to Cloud

Build the server

Create a local project

Start the server

Use the SDK

Run the dashboard locally

Move the configuration to Cloud