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

# LLM settings

> Configure how Guild runs LLM calls for your account — managed Guild tokens or your own provider API keys.

LLM settings control which provider and credentials Guild uses when agents call `task.llm`. By default, agents use **managed** LLM access backed by your Guild tokens balance. You can switch to **bring your own key (BYOK)** by adding a provider API key.

LLM configuration is stored on an **account** (your user account or an organization), not on individual workspaces. Sessions in a workspace use the LLM settings for that workspace's owner account.

## Open LLM settings

The console **Settings** panel lists **LLM Settings** after **Credentials** and before **Usage**.

### Personal account

<Steps>
  <Step title="Open Settings">Click your profile in the top-left corner, then select **Settings**.</Step>
  <Step title="Go to LLM Settings">In the settings sidebar, click **LLM Settings**.</Step>
</Steps>

Direct URL: `https://app.guild.ai/settings/llm-settings`

### Organization

Organization LLM settings apply to workspaces owned by that organization. Only organization **admins** can open this section.

<Steps>
  <Step title="Open your organization">Switch to the organization from the profile menu.</Step>
  <Step title="Open Settings">Go to **Settings** for the organization.</Step>
  <Step title="Go to LLM Settings">In the settings sidebar, click **LLM Settings**.</Step>
</Steps>

Direct URL: `https://app.guild.ai/organizations/{org-name}/settings/llm-settings`

## Managed vs BYOK

| Mode        | When it applies                            | Billing                                                                    |
| ----------- | ------------------------------------------ | -------------------------------------------------------------------------- |
| **Managed** | No active provider API keys on the account | LLM usage draws from your **Guild tokens balance**                         |
| **BYOK**    | At least one active provider API key       | Calls use your provider account; your Guild tokens balance is not consumed |

The page shows your current mode as **LLM Tier**:

* **Managed ({tier})** — Guild runs LLMs on your behalf using managed infrastructure.
* **BYOK (Bring Your Own Key)** — Guild routes LLM calls through your default API key.

When you add your first API key, the account switches from managed to BYOK automatically. When you delete your last active key, Guild switches back to managed.

## API keys

Provider API keys live on the account. Adding one switches the account to BYOK; removing the last one returns it to managed.

### Add an API key

Click **Add API key** in the page header.

| Field             | Description                                                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider**      | Anthropic, OpenAI, Gemini, or Meta                                                                                                                                                                    |
| **Name**          | A label you choose (for example, `Production` or `Testing`)                                                                                                                                           |
| **API Key**       | The key from your provider console                                                                                                                                                                    |
| **Default model** | The model Guild uses when this key is selected but no specific model is requested. The field is pre-filled with the platform default for the chosen provider; change it to any model the key can use. |

The platform default model for each provider is:

| Provider  | Default model       |
| --------- | ------------------- |
| Anthropic | `claude-sonnet-4-6` |
| OpenAI    | `gpt-4o`            |
| Gemini    | `gemini-3.5-flash`  |
| Meta      | `muse-spark-1.1`    |

Guild stores keys securely and shows only a masked value in the table (first and last few characters).

### Update an API key

Select **Edit** from the row menu to update an existing key.

| Field             | Description                                           |
| ----------------- | ----------------------------------------------------- |
| **Default model** | The model used for LLM calls with this key. Required. |

### Default model

Each API key has a **default model** — the model used when that key is selected but the request doesn't resolve to a more specific allowed model. It is set when you add the key (pre-filled with the [platform default](#add-an-api-key) for the provider) and can be changed later from the key's row.

### Manage keys

The keys table lists each key's provider, masked API key, created date, and creator. Use the row menu to:

* **Set as default** — Use this key for LLM calls when multiple keys exist.
* **Delete** — Archive the key. Archived keys appear when you filter to **Archived keys**.

Use **Search** and the status filter (**All keys**, **Active keys**, **Archived keys**) to find keys.

<Warning>
  Deleting your **last** active key returns the account to **managed** mode. Deleting the **default** key promotes another active key to default if one exists.
</Warning>

## Model policies

Model policies control which LLMs agents can call. A policy (a "rule") attaches an API key to a scope with a set of allowed models. Policies are an **allowlist**: a model is available only if a matching rule allows it.

Model policy configuration is available only in **BYOK** mode. The **Account default** and **Overrides** sections, along with the workspace-level and workspace agent-level **Models** sections, appear only when the account has at least one active API key. In **managed** mode, these sections are hidden because LLM calls use Guild-provided tokens and there are no rules to assign.

### Account default

Set the account default rules under **Models** in **Settings > LLM Settings**. Rules are ranked, and the first matching rule wins. Each rule allows one of:

| Scope               | When to use                                         |
| ------------------- | --------------------------------------------------- |
| **All models**      | Allow every model the provider exposes for the key. |
| **Specific models** | Restrict the key to a chosen set of models.         |

For a **Specific models** rule, you can:

* Select standard models from the built-in catalog.
* Enter custom globs to match model families, for example `haiku-*` or `gpt-4o-*`.

Use **Add rule** to add a rule, the row menu to edit or remove one, and the drag handle to reorder. Changes apply immediately.

This section is hidden on the **LLM Settings** page in **managed** mode (no active API keys). It appears once the account has at least one active API key.

### Overrides

The **Overrides** section, below **Models** in **Settings > LLM Settings**, lists every workspace, agent, and workspace-agent that sets its own rules instead of the account default. An override **replaces** the account default entirely — there is no merging.

Filter the list by scope — **Workspaces**, **Agents**, or **Workspace agents** — and use **Add override** to create one or the row menu to edit it. **Reset all overrides** clears every override and returns all scopes to the account default.

Like **Models**, this section is hidden on the **LLM Settings** page in **managed** mode and appears once the account has at least one active API key.

### Rule hierarchy and inheritance

Model rules resolve down an inheritance chain so you can set a policy once and refine it where needed, from least to most specific:

```text theme={null}
Account (root) -> Workspace -> Agent -> Workspace agent
```

Each sub-level inherits the rules of its parent until you override it; the most specific level that has its own rules wins. Overriding pre-copies the inherited rules to the level you are editing so you can adjust them from a known starting point.

<Note>
  API keys themselves are always inherited from the owning account and cannot be replaced at a lower level. Only model rules can be overridden.
</Note>

You can set an override directly from the scope it applies to:

* **Workspace** — open the workspace and click **Models** in the sidebar. The page shows the inherited account rules; **Add rule** overrides them for this workspace, and **Reset to inherited** drops the override. If the owning account has no active API keys, this page shows an empty state — **Using Guild-provided tokens** — instead of the editor, and model controls become available once you add an API key to the account.
* **Workspace agent** — open the agent inside a workspace and use the **Models** section on its detail page. It works the same way, overriding the rules for that agent in that workspace. If the owning account has no active API keys, the **Models** section is hidden entirely.

A status banner shows whether the level is **Inherited** (using the account default) or **Overridden** (using its own rules).

### Manage policies from the CLI

The Guild CLI manages model policies under `guild llm policy`. Each policy attaches an API key to a target — a workspace, agent, or workspace-agent — with an optional model allowlist.

| Command                                                                        | Description                                                                                                             |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `guild llm policy list <api-key-id>`                                           | List the policies attached to an API key. Add `--json` for machine-readable output.                                     |
| `guild llm policy create --key-id <id> --target-id <id> [--models <patterns>]` | Create a policy. Omit `--models` to allow all models; pass comma-separated globs (e.g. `haiku-*,sonnet-*`) to restrict. |
| `guild llm policy update <policy-id> (--models <patterns> \| --all-models)`    | Replace a policy's allowed models. `--all-models` clears the restriction; `--models ""` allows none.                    |
| `guild llm policy delete <policy-id>`                                          | Delete a policy. Removing the last policy on a target returns it to inheriting the account default.                     |
| `guild llm policy reorder <target-id> --policies <id1,id2,...>`                | Reorder a target's policies; pass all of the target's policy IDs in the desired rank.                                   |

Model values follow the same semantics as the console: a list of patterns (with optional `*` wildcards) allows those models, all models means unrestricted, and an empty list disables the key for that target.

## Daily token limit

When you use BYOK, you can set a **Daily token limit** below the keys table. All LLM requests are rejected after the account exceeds this limit for the day. The limit resets at midnight UTC. Leave the field empty for unlimited usage.

This limit applies to LLM usage on the account while BYOK is active.

## Guild tokens balance

When the account is in **managed** mode, the page shows your **Guild tokens balance**. The balance is indicative and may not update in real time.

## How agents use these settings

Agents do not embed provider API keys in code. At runtime, Guild resolves LLM configuration for each session from the workspace owner's account settings.

See [LLMs](/guide/llms) for calling `task.llm` from agent code and [Credentials](/platform/credentials) for connecting third-party services agents use as tools.