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

# AI Setup and Configuration

> Configure AI profiles, models, and authentication in Glyph

Set up AI assistance in Glyph by creating profiles, configuring providers, and managing authentication credentials.

## Initial Setup

**1. Open AI Settings**

Navigate to **Settings → AI** or press the settings keyboard shortcut and select the AI tab.

**2. Select a Profile**

Glyph creates default profiles for all supported providers. Select the profile for your preferred provider (OpenAI, Anthropic, Gemini, etc.).

**3. Configure Provider**

Each profile has provider-specific settings:

* **Service**: The AI provider (OpenAI, Anthropic, Gemini, OpenRouter, Ollama, OpenAI-compatible, Codex)
* **Model**: Select from available models (fetched from the provider)
* **Base URL**: Custom endpoint (optional, for OpenAI-compatible or self-hosted)
* **Headers**: Additional HTTP headers (optional)
* **Allow Private Hosts**: Enable for local models (Ollama, localhost endpoints)

**4. Add Authentication**

Most providers require an API key:

* **OpenAI, Anthropic, Gemini, OpenRouter**: API key required
* **Ollama, OpenAI-compatible**: Optional (depends on endpoint)
* **Codex**: OAuth authentication (no API key needed)

API keys are stored in `.glyph/app/ai_secrets.json` in your space directory.

**5. Select Model**

Click the model dropdown to fetch and select from available models. The list is retrieved from the provider API.

## Profile Configuration

### Service Selection

Each profile is associated with a single provider. To use multiple providers, create or switch between profiles.

Available services:

* `openai` - OpenAI GPT models
* `anthropic` - Anthropic Claude models
* `gemini` - Google Gemini models
* `openrouter` - OpenRouter multi-model API
* `ollama` - Ollama local models
* `openai_compat` - Any OpenAI-compatible endpoint
* `codex_chatgpt` - Codex ChatGPT OAuth

### Model Selection

Click **Model** to open the model selector:

1. **Automatic Model List**: Glyph fetches available models from the provider API
2. **Search Models**: Type to filter the model list
3. **Model Details**: Hover over the info icon to view:
   * Context length
   * Pricing (for OpenRouter)
   * Supported parameters
   * Input/output modalities
4. **Manual Entry**: If model fetch fails, type the model ID manually

### Advanced Options

#### Base URL

Override the default API endpoint:

* **OpenAI**: `https://api.openai.com/v1`
* **Anthropic**: `https://api.anthropic.com`
* **Gemini**: `https://generativelanguage.googleapis.com`
* **OpenRouter**: `https://openrouter.ai/api/v1`
* **Ollama**: `http://localhost:11434/v1`
* **OpenAI-compatible**: `http://localhost:11434/v1` (default)

> [!NOTE]
>
> Custom base URLs are validated for SSRF attacks. Enable **Allow Private Hosts** to use `http://localhost` or private IP addresses.

#### Custom Headers

Add additional HTTP headers to requests:

```json theme={null}
[
  { "key": "X-Custom-Header", "value": "my-value" },
  { "key": "Authorization", "value": "Bearer custom-token" }
]
```

Headers are applied to all requests for this profile.

#### Reasoning Effort (Codex only)

For models that support reasoning modes (e.g., `o1`, `o3-mini`):

* **low** - Faster responses, less thorough
* **medium** - Balanced (default)
* **high** - More thorough, slower

The option appears only when using Codex with a reasoning-capable model.

## API Key Management

### Setting an API Key

> [tab] Via Settings UI
>
> 1. Select a profile that requires an API key
> 2. Click **Set API Key** in the authentication section
> 3. Paste your API key
> 4. Click **Save**
>
> The key is encrypted and stored in `.glyph/app/ai_secrets.json`.

> [tab] Manual File Edit
>
> Create or edit `.glyph/app/ai_secrets.json` in your space:
>
> ```json theme={null}
> {
>   "<profile-id>": "sk-your-api-key-here"
> }
> ```
>
> Profile IDs are UUIDs visible in the settings UI or `ai.json`.

### Security

* API keys are stored **per space**, not globally
* Keys are stored in `.glyph/app/ai_secrets.json` (add to `.gitignore`)
* File uses atomic writes to prevent corruption
* Keys are never logged or sent to Glyph servers
* Each space has independent API key storage

### Clearing an API Key

In Settings → AI, click **Clear API Key** for the active profile. This removes the key from `ai_secrets.json`.

## Profile Storage

Profile configurations (excluding API keys) are stored in:

```
~/.config/glyph/ai.json  (Linux)
~/Library/Application Support/glyph/ai.json  (macOS)
%APPDATA%/glyph/ai.json  (Windows)
```

Example `ai.json`:

```json theme={null}
{
  "profiles": [
    {
      "id": "uuid-here",
      "name": "OpenAI",
      "provider": "openai",
      "model": "gpt-4o",
      "base_url": null,
      "headers": [],
      "allow_private_hosts": false,
      "reasoning_effort": null
    }
  ],
  "active_profile_id": "uuid-here"
}
```

## Default Profiles

On first launch, Glyph creates these default profiles:

* **OpenAI** - Empty model, requires API key
* **OpenAI-compatible** - Points to `http://localhost:11434/v1`
* **OpenRouter** - Empty model, requires API key
* **Anthropic** - Empty model, requires API key
* **Gemini** - Empty model, requires API key
* **Ollama** - Empty model, allows private hosts
* **Codex (ChatGPT OAuth)** - Model `codex`, OAuth authentication

## Troubleshooting

### "API key not set for this profile"

Add your API key in Settings → AI → Authentication.

### "Model list failed"

Check:

1. API key is valid and has correct permissions
2. Network connectivity
3. Base URL is correct (if customized)
4. Provider service is operational

### "http base\_url blocked"

Enable **Allow Private Hosts** in advanced settings to use `http://` URLs.

### Model dropdown is empty

Type the model ID manually in the model field. The app will use it even if the model list fetch failed.

## Next Steps

> [card] [OpenAI Setup](https://docs.glyphformac.com/ai/providers/openai.md)
>
> Configure OpenAI provider

> [card] [Anthropic Setup](https://docs.glyphformac.com/ai/providers/anthropic.md)
>
> Configure Anthropic Claude

> [card] [Ollama Setup](https://docs.glyphformac.com/ai/providers/ollama.md)
>
> Run models locally

> [card] [Chat Modes](https://docs.glyphformac.com/ai/chat-modes.md)
>
> Learn about chat vs create modes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.