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

# Models & API Keys

> Pick a model, set sampling, and store keys in the macOS keychain

Swap models from the title bar, tune sampling, and keep your API key in the macOS keychain — never in a file.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    llm="gpt-4o-mini",
)
# The model you pick in the app is passed to the agent as llm=...
agent.start("Say hello")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Pill[🏷️ Model Pill] --> Model[🧠 Model]
    Key[🔑 API Key] --> Keychain[(macOS Keychain)]
    Model --> Reply[✅ Reply]

    classDef pill fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef model fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef key fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef reply fill:#10B981,stroke:#7C90A0,color:#fff

    class Pill pill
    class Model,Keychain model
    class Key key
    class Reply reply
```

## Quick Start

<Steps>
  <Step title="Open the model combobox">
    Click the model pill in the title bar. It suggests common models and accepts any string.
  </Step>

  <Step title="Set your API key">
    In **Settings → Models → API key**, paste your key. It is stored in the macOS keychain.
  </Step>

  <Step title="Tune sampling (optional)">
    Adjust `temperature`, `max_tokens`, or `top_p` in the Models section.
  </Step>
</Steps>

***

## Suggested Models

The combobox suggests these and accepts any other string:

| Model                      | Notes            |
| -------------------------- | ---------------- |
| `gpt-4o-mini`              | Default          |
| `gpt-4o`                   |                  |
| `claude-sonnet-4-20250514` |                  |
| `claude-opus-4-20250514`   |                  |
| `gemini-2.0-flash`         |                  |
| `ollama/llama3.2`          | Local via Ollama |

***

## Sampling & Endpoint

| Field         | Default | Effect                                           |
| ------------- | ------- | ------------------------------------------------ |
| `temperature` | `0.7`   | Higher is more varied; `0` is near-deterministic |
| `max_tokens`  | `0`     | `0` lets the model decide                        |
| `top_p`       | `1`     | Nucleus sampling                                 |
| `base_url`    | `""`    | Override for a proxy, Azure, or a local server   |

<Note>
  Sampling values are forwarded only when you change them from their defaults, so a provider default you set elsewhere is never overridden unasked.
</Note>

***

## Where Keys Live

The `api_key` is stored in the macOS keychain (service `ai.praison.desktop`) and stripped before `settings.json` is written.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Save[💾 Save settings] --> Split{Secret?}
    Split -->|api_key| Keychain[(🔐 macOS Keychain)]
    Split -->|everything else| File[(settings.json)]

    classDef save fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef split fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef out fill:#10B981,stroke:#7C90A0,color:#fff

    class Save save
    class Split split
    class Keychain,File out
```

<Warning>
  Your `api_key` never touches `settings.json` — it lives only in the keychain. Clearing it removes the credential from the environment on the next turn.
</Warning>

***

## Choosing a Setup

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{Where does<br/>the model run?} -->|Cloud provider| Cloud[Set api_key]
    Start -->|Local Ollama| Local[Set base_url]
    Start -->|Enterprise proxy| Both[Set api_key + base_url]

    classDef q fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef opt fill:#10B981,stroke:#7C90A0,color:#fff

    class Start q
    class Cloud,Local,Both opt
```

| Setup                                   | Set                      |
| --------------------------------------- | ------------------------ |
| Cloud model (OpenAI, Anthropic, Gemini) | `api_key`                |
| Local Ollama                            | `base_url`               |
| Enterprise proxy / Azure                | `api_key` and `base_url` |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Leave api_key blank to use the environment">
    If you already export `OPENAI_API_KEY`, leave the field blank and the engine uses the environment key.
  </Accordion>

  <Accordion title="Restart after changing key or base_url">
    Both are marked "requires restart". Relaunch so the engine routes to the new credential or endpoint.
  </Accordion>

  <Accordion title="Use base_url for local models">
    Point `base_url` at your local server (for example Ollama or LM Studio) to run entirely on-device.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Settings Reference" icon="sliders" href="/docs/features/desktop/settings">
    Every Models field and its default
  </Card>

  <Card title="Data & Privacy" icon="lock" href="/docs/features/desktop/data">
    How secrets are kept off disk
  </Card>
</CardGroup>