Skip to main content
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 an inference provider credential. 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. Together these settings act as a central model gateway: credentials are held server-side and never distributed to agents, model policies control which models each workspace and agent may call, the daily token limit caps spend, and every call is attributed to its workspace, agent, and user in Insights.

​
Open LLM settings

The console Settings panel lists LLM Settings after Credentials.

​
Personal account

1

Open Settings

Click your profile in the top-left corner, then select Settings.
2

Go to LLM Settings

In the settings sidebar, click LLM Settings.
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.
1

Open your organization

Switch to the organization from the profile menu.
2

Open Settings

Go to Settings for the organization.
3

Go to LLM Settings

In the settings sidebar, click LLM Settings.
Direct URL: https://app.guild.ai/organizations/{org-name}/settings/llm-settings

​
Managed vs BYOK

The page shows your current mode as LLM Tier:
  • Managed () — Guild runs LLMs on your behalf using managed infrastructure.
  • BYOK (Bring Your Own Key) — Guild routes LLM calls through your own inference provider credentials, selected by your account’s model policies.
When you add your first credential, the account switches from managed to BYOK automatically. When you delete your last active credential, Guild switches back to managed.

​
Inference provider credentials

Credentials live on the account. Adding one switches the account to BYOK; removing the last one returns it to managed. An inference provider is the endpoint Guild authenticates to. A model publisher is who made the model. For a publisher’s own API these are the same party, but a provider can serve models from several publishers — so a credential carries one access per publisher it unlocks, and model policies bind to a specific access rather than to the credential as a whole. Providers differ in how they authenticate, which is why this is a credential and not simply a key: the fields in the form are derived from the provider you pick.

​
Add a credential

Click Add API key in the page header. The platform default model for each publisher is: Guild stores credentials securely and shows only a masked value in the table (first and last few characters).

​
Update a credential

Select Edit from the row menu to update an existing credential.

​
Rotate a credential

Rotate a credential to swap in a new secret without disturbing the model policies bound to its accesses. Guild validates the new secret, creates a replacement credential carrying the old one’s policies and default model, and archives the old credential immediately. Usage already recorded stays attributed to the credential that incurred it. Select Rotate key from the credential’s row menu and paste the new secret. Rotating cannot be undone, and an already-archived credential cannot be rotated.

​
Default model

Each credential has a default model — the model used when that credential is selected but the request doesn’t resolve to a more specific allowed model. It is set when you add the credential (pre-filled with the platform default for the publisher) and can be changed later from the credential’s row.

​
Manage credentials

The table lists each credential’s provider, masked secret, created date, and creator. Use the row menu to:
  • Edit — Change the credential’s default model.
  • Rotate key — Replace the credential’s secret while keeping its policies. See Rotate a credential.
  • Delete — Archive the credential. Archived credentials appear when you filter to Archived keys.
Use Search and the status filter (All keys, Active keys, Archived keys) to find credentials. Which credential serves a request is decided by your account’s model policies, not by marking one as the default.
Deleting a credential also removes every model policy bound to its accesses. To replace its secret without losing those policies or its default model, rotate it instead.Deleting your last active credential returns the account to managed mode.

​
Model policies

Model policies control which LLMs agents can call. A policy (a “rule”) binds a credential access 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 credential. 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: 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 credentials). It appears once the account has at least one active credential.

​
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 credential.

​
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:
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.
Credentials themselves are always inherited from the owning account and cannot be replaced at a lower level. Only model rules can be overridden.
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 credentials, this page shows an empty state — Using Guild-provided tokens — instead of the editor, and model controls become available once you add a credential 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 credentials, 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).

​
Find a credential’s ID from the CLI

guild llm policy create needs the ID of the credential a policy binds to. List an account’s credentials to find it:
The output has one row per credential:

​
Manage policies from the CLI

The Guild CLI manages model policies under guild llm policy. Each policy binds a credential access to a target — a workspace, agent, or workspace-agent — with an optional model allowlist. 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 that access for the target.

​
Manage policies from chat

Smith can do the same work conversationally. Ask it to list your credentials, show the policies on a target, restrict a credential to certain models, or change policy priority. Smith presents the exact change it intends to make and waits for your approval before creating, updating, deleting, or reordering anything.

​
Daily token limit

When you use BYOK, you can set a Daily token limit below the credentials 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 credentials in code. At runtime, Guild resolves LLM configuration for each session from the workspace owner’s account settings. See LLMs for calling task.llm from agent code and Credentials for connecting third-party services agents use as tools.

​
Model selection

Guild resolves the provider and model for each task.llm call from policies and agent preferences.

​
Policy resolution

A policy pairs a credential access with a list of allowed models. To find the active policy set, Guild walks this hierarchy and stops at the first level that has any policies defined:
  1. Workspace agent — policies on a specific agent installed in the workspace
  2. Agent — policies on the agent definition
  3. Workspace — policies on the workspace
  4. Account — policies on the user or organization account
Only the matching level applies. Policies from different levels are not merged.

​
Preferences

An agent can declare preferences, each naming a provider and optionally a model. Guild evaluates them against the active policies in order:
  • A preference with no model selects the policy’s first allowed model, or the credential’s default model when the policy lists none.
  • A preference with a model is matched against the policy’s allowed models as wildcard patterns, so claude-haiku-* matches any Claude Haiku variant. A policy with no allowed-models list matches every model.

​
Fallback

If no preference matches, or the agent declares none, Guild falls back to the first available policy and its first allowed model, or that credential’s default model.