> ## 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.

# Quickstart

> Create a cloud project and call your first agent.

## Prerequisites

* **Node.js 20+** — [install](https://nodejs.org)

## 1. Create and deploy a project

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

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

<Accordion title="Optional: install the CLI globally">
  ```bash theme={null}
  npm install -g @polpo-ai/cli
  ```

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

<Note>
  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.
</Note>

## 2. Load the generated credentials

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

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

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

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

```bash theme={null}
npx @polpo-ai/cli deploy
```

See [Agent Definition](/docs/agents/definition) for the configuration fields and [Deploy](/docs/platform/deploy) for deploy flags and resource behavior.

## 5. Use the TypeScript SDK

```bash theme={null}
npm install @polpo-ai/sdk
```

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