Models & Providers

Pi-tree works with a wide range of LLM providers and models. It doesn't need frontier-class models — reading and comprehension are more about context and conversation than raw reasoning. Smaller, faster models work well and keep costs low (or free with local inference).

Cloud APIs

The cheapest options that work well for reading:

Provider	Model	Notes
DeepSeek	deepseek-v4-flash	Very cheap, strong reading comprehension
Google	gemini-2.5-flash	Fast, large context window
Anthropic	claude-haiku-4-20250514	Fast, great quality-to-cost ratio
Zhipu	glm-5-turbo	Good Chinese + English bilingual support

To use a cloud provider, set these variables in your .env file:

PI_PROVIDER=deepseek
PI_API_KEY=your-api-key-here
PI_MODEL=deepseek-v4-flash

TIP

You can also set PI_LOOKUP_MODEL to a cheaper or faster model for dictionary lookups, keeping the primary model for reading sessions.

Local Models

Run models completely offline with no API costs using Ollama or LM Studio. Gemma 4 (12B, 256K context) and Qwen 3.6 are good starting points — explore what works for your hardware and reading language.

Setup with Ollama

1. Install Ollama and pull a model:

ollama pull gemma4:12b

2. Point pi-tree at your local server in .env:

PI_PROVIDER=openai                              # Ollama exposes an OpenAI-compatible API
PI_API_KEY=not-needed
PI_BASE_URL=http://localhost:11434/v1            # Ollama default
PI_MODEL=gemma4:12b

Setup with LM Studio

1. Install LM Studio and download a model
2. Start the local server in LM Studio
3. Configure .env:

PI_PROVIDER=openai
PI_API_KEY=not-needed
PI_BASE_URL=http://localhost:1234/v1             # LM Studio default
PI_MODEL=your-model-name

Docker users

When running pi-tree in Docker, two extra steps are needed:

1. Bind to all interfaces — LM Studio defaults to 127.0.0.1 (localhost only). Docker containers can't reach it. Run lms server start --bind 0.0.0.0 or set "networkInterface": "0.0.0.0" in ~/.lmstudio/.internal/http-server-config.json.

2. Use host.docker.internal — Replace localhost with host.docker.internal in your base URL. On Linux, add extra_hosts: ["host.docker.internal:host-gateway"] to your Compose file.

See Self-Hosting — Local LLM for a complete walkthrough.

Compatibility flags

When using models.json with local providers, add compat flags to avoid silent failures:

{
  "providers": {
    "lmstudio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "not-needed",
      "compat": { "supportsDeveloperRole": false },
      "models": [
        { "id": "qwen/qwen3.6-27b" }
      ]
    }
  }
}

Most local servers (LM Studio, Ollama, llama.cpp) only support system and user message roles. Setting "supportsDeveloperRole": false prevents the AI framework from sending unsupported developer role messages, which would cause empty responses.

Multi-Provider Setup

For advanced setups — like using Ollama for offline reading and DeepSeek for cloud — use Pi's native models.json configuration. This lets you define multiple providers and switch between them at runtime.

Configure models.json

Place the file at ~/.pi/agent/models.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "gemma4:12b" },
        { "id": "qwen3.6:8b" }
      ]
    },
    "deepseek": {
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        { "id": "deepseek-v4-flash" }
      ]
    }
  }
}

How resolution works

Environment variables and models.json merge automatically:

• If you set PI_PROVIDER + PI_API_KEY in .env and have providers in models.json, all providers are available
• The env var provider's API key takes precedence over models.json for that specific provider
• You can use both approaches together — they complement each other

Docker with models.json

Mount the file into the container:

volumes:
  - ~/.pi/agent/models.json:/root/.pi/agent/models.json:ro

Runtime Model Switching

TIP

You can change models at runtime through the Settings UI — no restart needed. This is especially useful with multi-provider setups: switch between a local model for casual reading and a cloud model for complex analysis on the fly.

Usage Dashboard

Pi-tree tracks token usage (input, output, cache) and estimated cost for every AI interaction — reading sessions, router chat, and dictionary lookups. The Usage page breaks it down by time range, source, and provider, and each session shows a live usage badge above the chat input. Everything is stored locally in your database; nothing is reported anywhere.

What's Next?

• Getting Started — Set up pi-tree for the first time
• Self-Hosting — Docker Compose, custom skills, env vars, and more