> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Run the open-source Polpo server locally.

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

## Build the server

```bash theme={null}
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:

```text theme={null}
workspace/
└── .polpo/
    ├── polpo.json
    ├── teams.json
    └── agents.json
```

```json .polpo/polpo.json theme={null}
{
  "project": "local-project",
  "settings": {
    "storage": "file"
  }
}
```

```json .polpo/teams.json theme={null}
[
  {
    "name": "default",
    "description": "Default team"
  }
]
```

```json .polpo/agents.json theme={null}
[
  {
    "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:

```bash theme={null}
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:

```bash theme={null}
curl http://localhost:3890/api/v1/health
```

Call chat completions at the OpenAI-compatible path:

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

## Use the SDK

```typescript theme={null}
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](/docs/platform/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:

```bash theme={null}
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:

```bash theme={null}
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](/docs/platform/deploy) and [Model Gateway](/docs/platform/llm-gateway).