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

# LLM Connections

> Configure multiple model providers, set defaults, and control which connection each session uses.

An LLM connection is a saved provider configuration — which provider, which model, which credentials, and any endpoint details. Keeping several connections lets you switch between backends without re-entering keys: one for Anthropic, one for a local endpoint, one for a gateway. This page covers the fields, how a session picks a connection, and how to manage them. For endpoint specifics, see [API Providers](/reference/config/custom-endpoint).

## Where connections live

Connections are stored as the `llmConnections` array in the [config file](/reference/config/config-file) (`~/.synti/config.json`). Their secrets are held separately in the encrypted [credential store](/reference/config/credentials) and referenced by slug.

## Connection fields

| Field               | Required | Description                                           |
| ------------------- | -------- | ----------------------------------------------------- |
| `slug`              | yes      | URL-safe unique identifier, e.g. `anthropic-default`. |
| `name`              | yes      | Display name shown in the UI.                         |
| `providerType`      | yes      | Provider backend (see table below).                   |
| `authType`          | yes      | How the connection authenticates.                     |
| `createdAt`         | yes      | Creation time in Unix milliseconds.                   |
| `defaultModel`      | no       | Model used when the session doesn't specify one.      |
| `baseUrl`           | no       | Custom endpoint for compatible providers.             |
| `models`            | no       | Explicit model list with per-model capabilities.      |
| `midStreamBehavior` | no       | How messages sent mid-response are handled.           |

```json theme={null}
{
  "slug": "anthropic-default",
  "name": "Anthropic",
  "providerType": "anthropic",
  "authType": "api_key",
  "defaultModel": "claude-sonnet-4-5",
  "createdAt": 1731000000000
}
```

### Provider types

| `providerType`  | For                                           |
| --------------- | --------------------------------------------- |
| `anthropic`     | Anthropic's direct API (default).             |
| `openai`        | OpenAI.                                       |
| `google`        | Google Gemini.                                |
| `openrouter`    | OpenRouter gateway.                           |
| `groq`          | Groq.                                         |
| `mistral`       | Mistral.                                      |
| `xai`           | xAI (Grok).                                   |
| `openai_compat` | Any OpenAI-compatible endpoint via `baseUrl`. |

### Auth types

| `authType`              | Meaning                                   |
| ----------------------- | ----------------------------------------- |
| `api_key`               | Static API key.                           |
| `api_key_with_endpoint` | API key plus a custom base URL.           |
| `oauth`                 | OAuth sign-in (e.g. a subscription plan). |
| `environment`           | Read the key from environment variables.  |
| `none`                  | No auth (public or local endpoints).      |

## How a session picks a connection

When you send a message, Synti resolves the connection in this order:

1. **Session connection** — locked in after the session's first message.
2. **Workspace default** — the default set for the active workspace.
3. **Global default** — `defaultLlmConnection` in the config.
4. **First connection** — the first entry in the list, as a fallback.

<Note>
  A session locks to its connection after the first message so a conversation stays coherent on one model. To use a different provider, start a new session.
</Note>

## Managing connections

Open **Settings → AI** to add, edit, delete, and validate connections. From there you can:

* Set the global default and per-workspace defaults.
* Validate that a connection actually reaches its provider.
* Toggle per-model image support for custom endpoints without editing JSON.
* Choose mid-stream behavior per connection.

You can also list connections from the terminal client with `synti-cli connections` — see the [CLI reference](/reference/cli).

### Mid-stream behavior

If you send a message while the agent is still responding, the connection decides what happens:

* **`queue`** — hold the new message until the current turn finishes. Default for Anthropic.
* **`steer`** — inject the message into the turn in progress to redirect it.

### Custom endpoint capabilities

For `openai_compat` connections, declare what the endpoint supports per model — for example `contextWindow` and `supportsImages` — so Synti sizes requests and enables images correctly. See [API Providers](/reference/config/custom-endpoint).

## Related

<CardGroup cols={2}>
  <Card title="API Providers" icon="globe" href="/reference/config/custom-endpoint">
    Base URLs, model IDs, and custom endpoints.
  </Card>

  <Card title="Credentials" icon="lock" href="/reference/config/credentials">
    Where each connection's key is encrypted.
  </Card>

  <Card title="Config File" icon="file-code" href="/reference/config/config-file">
    The file that holds the connections array.
  </Card>

  <Card title="Environment Variables" icon="terminal" href="/reference/config/environment-variables">
    Supply provider keys at launch.
  </Card>
</CardGroup>