# Configuration

## URL Resolution

The extension resolves the llama.cpp server URL using a priority chain. Higher priority options override lower ones.

### Priority Order

1. **Per-project config** (highest) — `.pi/settings.json` in your project root
2. **Environment variable** — `LLAMA_SERVER_URL`
3. **Global settings** — `~/.pi/agent/settings.json`
4. **Default** — `http://127.0.0.1:8080` (lowest)

### 1. Per-Project Configuration

Create or edit `.pi/settings.json` in your project root:

```json
{
  "llamaServerUrl": "http://127.0.0.1:8080"
}
```

This setting applies only to the current project.

### 2. Environment Variable

Set the `LLAMA_SERVER_URL` environment variable:

```bash
# Single server
export LLAMA_SERVER_URL="http://127.0.0.1:8080"

# Multiple servers (semicolon-separated)
export LLAMA_SERVER_URL="http://127.0.0.1:8080;http://127.0.0.1:8081;http://10.0.0.5:8080"
```

Environment variables take precedence over global settings but are overridden by project config.

### 3. Global Configuration

Edit `~/.pi/agent/settings.json`:

```json
{
  "llamaServerUrl": "http://127.0.0.1:8080"
}
```

This applies to all projects unless overridden by project config or environment variable.

### 4. Default

If no configuration is found, the extension connects to `http://127.0.0.1:8080`.

## Multiple Servers

Connect to multiple llama.cpp servers simultaneously by separating URLs with semicolons:

```json
{
  "llamaServerUrl": "http://127.0.0.1:8080;http://127.0.0.1:8081;http://10.0.0.5:8080"
}
```

Each server gets its own provider and model list. The `/models` command displays all models from all servers, labeled with their server URL.

## LiteLLM Configuration

Connect to a [LiteLLM](https://github.com/BerriAI/litellm) proxy for remote model access.

### Priority Order

1. **Per-project config** — `.pi/settings.json`
2. **Environment variable** — `LITELLM_URL`
3. **Global settings** — `~/.pi/agent/settings.json`
4. **Default** — `null` (not configured)

### Per-Project Configuration

```json
{
  "litellmUrl": "http://localhost:4000"
}
```

### Environment Variable

```bash
export LITELLM_URL="http://localhost:4000"
```

### Global Configuration

```json
{
  "litellmUrl": "http://localhost:4000"
}
```

### Running Both Simultaneously

You can run both a local llama.cpp server and a LiteLLM proxy at the same time:

```json
{
  "llamaServerUrl": "http://127.0.0.1:8080",
  "litellmUrl": "http://localhost:4000"
}
```

Each gets its own provider and model list.

> **Note:** LiteLLM proxies do not support SSE for model loading progress. The extension falls back to polling for loading status updates.

## Custom Server Names

Replace the default provider names (e.g., `"Llama.cpp"`) with human-readable names.

### Llama.cpp Server Names

**Per-project config:**

```json
{
  "llamaServerUrl": "http://127.0.0.1:8080",
  "llamaServerName": "Local Development"
}
```

**Environment variable:**

```bash
export LLAMA_SERVER_NAME="Local Development"
```

**Global settings:**

```json
{
  "llamaServerName": "Local Development"
}
```

### LiteLLM Server Names

**Per-project config:**

```json
{
  "litellmUrl": "http://localhost:4000",
  "litellmName": "Production LiteLLM"
}
```

The custom name appears in the provider list and login dialogs instead of the default `"LiteLLM"` format. The provider ID still uses the URL for authentication.

## API Key Authentication

### Using `/login` Command

1. Run `/login` in Pi
2. Select **"Use an API key"**
3. Select your provider from the list (you can type to filter by name)
4. Enter your API key

The provider list shows human-readable names (e.g., "Local Development", "Production LiteLLM"). You can type part of the name to filter.

### Using `auth.json` File

Configure API keys in `~/.pi/agent/auth.json`:

**Llama.cpp servers** use the provider ID `gateway-<hash>` (e.g. `gateway-3a4b5c6d`). The hash is derived from the server URL for uniqueness while keeping the ID short for small screens. Legacy format `llama-server=<url>` is also supported for backward compatibility:

```json
{
  "gateway-3a4b5c6d": {
    "type": "api_key",
    "key": "your-api-key-here"
  },
  "gateway-7e8f9a0b": {
    "type": "api_key",
    "key": "your-api-key-here"
  }
}
```

**LiteLLM proxies** use the provider ID `litellm=<url>`:

```json
{
  "litellm=http://localhost:4000": {
    "type": "api_key",
    "key": "your-litellm-api-key"
  }
}
```

> **Note:** LiteLLM proxies typically require API key authentication. The key is sent as a Bearer token in the `Authorization` header.

## Thinking Budgets

Configure token budgets for reasoning/thinking control.

### Default Budgets

| Level | Tokens | Description |
|-------|--------|-------------|
| `off` | 0 | Thinking disabled |
| `minimal` | 1,024 | Short reasoning steps |
| `low` | 2,048 | Light reasoning |
| `medium` | 8,192 | Balanced reasoning (default) |
| `high` | 16,384 | Extended reasoning |
| `xhigh` | -1 | Unlimited reasoning (extended) |
| `max` | -1 | Unlimited reasoning (maximum depth) |

### Custom Budgets

Override defaults in `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (per-project):

```json
{
  "thinkingBudgets": {
    "minimal": 256,
    "low": 1024,
    "medium": 2048,
    "high": 4096
  }
}
```

Only `minimal`, `low`, `medium`, and `high` are configurable. The `off` (0), `xhigh` (-1), and `max` (-1) levels are fixed.

## Troubleshooting

### Server Not Found

- Verify the server URL in your configuration
- Check that the server is running: `curl http://127.0.0.1:8080/health`
- Run `/models` to retry without timeout

### Model Fails to Load

- Check server logs for errors
- Verify the model file exists and is accessible
- Ensure you have sufficient memory
- Check API key if the server requires authentication

### Slow Server Response

- The extension has a 5-second timeout for server health checks
- Slow servers are skipped at startup with a warning
- Run `/models` to retry without timeout

### Auth Issues

- Verify the API key in `~/.pi/agent/auth.json`
- Ensure the provider ID matches your server URL exactly
- Run `/login` to re-authenticate