LLM Configuration Definition

The LLM Configuration enables the use of external LLM services for an organization. There is a single LLM configuration per org, maintained by org admins on the Connect / LLM page of the Web Console, and it can be managed as configuration-as-code:

cs llm config export          # print the current LLM config to stdout
cs llm config import FILE     # import the LLM config from a file, or from stdin when FILE is -

This page describes every field of that document. For a task-oriented walkthrough, see Manage LLM Configurations.

Structure Overview

providers:                # LLM service providers, keyed by name
  anthropic-main:
    anthropic:
      api_key: secret:anthropic-key

models:                   # The models exposed to clients and agents
- provider: anthropic-main
  name: claude-sonnet-4-6
  purposes: [GENERIC, CODING]
  aliases: [default]

session_config:           # Retention and auto archiving of conversations
  retention: 2592000s
  auto_archive: 604800s

sandbox_config:           # Auto configuration of LLM clients in workspaces
  clients:
    anthropic:
      provider: anthropic-main

discovery:                # Org-level agent and MCP server authorization
  named_mcp_servers:
    github:
      external:
        url: https://api.githubcopilot.com/mcp/
  global_mcp_servers:
  - ref: github

Top-Level Fields

Every defined provider also contributes to the LLM passthrough API, so that clients never need a provider-specific authentication token of their own:

• outside a sandbox: https://SYSTEM-DNS/ext/llm/api/orgs/ORG/passthrough/PROVIDER/...
• inside a workspace: http://PROVIDER.proxy.llm.g.sandbox/

Provider

The definition of an LLM service provider. Exactly one provider type must be specified per entry.

An API key should normally be stored as a Secret — an Admin Only secret is recommended — and referenced from the configuration as secret:NAME rather than written in plain text.

Provider.OpenAI

Example — an OpenAI API compatible service:

providers:
  openrouter:
    openai:
      api_key: secret:openrouter-key
      base_url: https://openrouter.ai/api/v1
      api: CHAT_COMPLETIONS

Provider.Anthropic

Provider.Gemini

Provider.Ollama

Provider.VertexAI

On GCP, all fields are optional, as they can be fetched from the metadata service. Specify them only to access Vertex AI in a project or region different from where the system is deployed.

VertexAI.IdentityFederation

Configures Workload Identity Federation, so that the per-user JWTs issued by Crafting are exchanged for GCP access tokens. When enabled, each request uses the calling user's JWT as the subject token, which makes usage attributable to individual users.

See Setup Identity Federation for how the trust is established on the cloud side.

Provider.Bedrock

Bedrock.IdentityFederation

Configures AWS Web Identity Federation, so that the per-user JWTs issued by Crafting are exchanged for temporary AWS credentials through AssumeRoleWithWebIdentity. When enabled, each request is signed with per-user STS credentials.

Model

A model exposed by one of the configured providers.

How a Model Is Selected

A client selects a model with a selector, resolved against the models list in one of three ways:

• By purpose, case insensitive. The first model that contains the purpose matches. If none matches:
• CODING_FIM and CODING_NES have no fallback — the corresponding features are disabled;
• every other purpose falls back to GENERIC.
• By provider:name, case sensitive, matching one specific model, with no fallback.
• By alias, case insensitive. The first model that contains the alias matches, with no fallback.

An empty selector is treated as the GENERIC purpose. Because ordering decides the winner, put the preferred model for a purpose first in the list.

Model.Dialect

The general model category, used as a hint for optimizing prompts.

Model.Properties

Example:

models:
- provider: anthropic-main
  name: claude-sonnet-4-6
  purposes: [GENERIC, CODING]
  aliases: [default, smart]
  dialect:
    source: anthropic
    model_class: claude-sonnet
  properties:
    context_window_limit: 200000
- provider: anthropic-main
  name: claude-haiku-4-5
  purposes: [FAST]

Model Mapping

A Model Mapping overlays the model selection defined by models, which is the base mapping from a selector — a purpose, an alias, or provider:name — to an actual model. It changes which model answers a selector, without changing how selectors are resolved.

Model mappings are used by an AI Agent to pin or downgrade the models used in its conversations.

Example — run everything generic on the fast model, and coding on a named model:

model_mapping:
  mappings:
    generic: fast
    coding: anthropic-main:claude-sonnet-4-6

SessionConfig

Settings related to LLM sessions.

Durations are expressed in seconds with an s suffix, e.g. 604800s for seven days.

Archiving is what releases the sandboxes created as an agent's execution environment, so auto_archive is the main control on the cost left behind by idle conversations. See Agentic Sessions for what archiving does to a conversation.

Example:

session_config:
  retention: 2592000s      # 30 days
  auto_archive: 604800s    # 7 days

SandboxConfig

Automatically sets up sandboxes to use LLM clients without further configuration.

SandboxConfig.Clients

Selects one provider for each supported client type. The client is configured against that provider's passthrough API inside the workspaces, so no API key is exposed to the workspace.

Clients.Anthropic

Clients.OpenAI

Clients.Gemini

Clients.Ollama

Example:

sandbox_config:
  clients:
    anthropic:
      provider: anthropic-main
    openai:
      provider: openrouter

Discovery

Discovery of agent and MCP information from existing sandboxes, shared within the org. An org admin must explicitly authorize the agents and MCP servers exposed by templates and sandboxes before they are shared with other agents at org level.

Every server in named_mcp_servers also gets a dedicated in-workspace endpoint at http://NAME.mcp.llm.g.sandbox. See MCP Servers.

Discovery.MCPServer

An MCP server entry. Exactly one of sandbox, external, or ref must be specified.

MCPServer.External

Defines an external service as an MCP server.

Example:

discovery:
  named_mcp_servers:
    github:
      external:
        url: https://api.githubcopilot.com/mcp/
        auth:
          token:
            login:
              name: github
      tool_call_policy:
        filters:
        - name:
            pattern: '*_read_*'
        - name:
            pattern: '*'
          action: BLOCK
  global_mcp_servers:
  - ref: github

Discovery.MCPServerPolicy

The policy for using MCP servers that are not defined in named_mcp_servers.

The servers in named_mcp_servers are predefined and approved by the org admin, and referencing them with ref is always allowed, regardless of this policy. A developer may, however, need a custom MCP server that is not predefined — for example in the explicit list of an AI agent. This policy decides whether such a server can be used.

A custom MCP server is any MCP server defined inline rather than referenced with ref, wherever it appears, including in global_mcp_servers. Only the definitions in named_mcp_servers are exempt, since that field is the approved registry the policy is defined against.

MCPServerPolicy.Matcher

Matches a custom MCP server definition.

Example:

discovery:
  mcp_server_policy:
    allow_custom_mcp_servers: true
    blocked_mcp_servers:
    - url:
        pattern: 'https://*.example.com/*'

Discovery.SandboxAgents

The authorized agents defined in templates.

SandboxAgents.TemplateFilter

Example — allow the agent templates of one folder and deny everything else:

discovery:
  sandbox_agents:
    templates:
    - name:
        pattern: 'agents/*'
      action: ALLOW
    - name:
        pattern: '*'
      action: DENY

Tool Call Policy

Defines the access control of tool calls, based on name matching. It is a firewall-like ruleset: the filters are evaluated in order, and the first matching filter decides the outcome. A tool call that matches no filter is allowed.

ToolCallPolicy.Filter

Example — allow read-style tools only:

tool_call_policy:
  filters:
  - name:
      pattern: '*_read_*'
  - name:
      pattern: '*'
    action: BLOCK

Because unmatched calls are allowed, a policy that should deny by default must end with a catch-all BLOCK filter, as above. See Tool Call Policy for more examples.

SimpleNameMatcher

A simplified matcher for resource names. Exactly one of the fields must be specified. Resource names are lower-cased, so there is no option for case sensitivity.

See Also

• LLM Config — the feature overview of central LLM configuration
• Manage LLM Configurations — the org admin walkthrough
• AI Agent Definition — the agent specification that consumes these models and MCP servers
• MCP Servers — authorizing and using MCP servers in sandboxes
• Setup Identity Federation — per-user credentials for Vertex AI and Bedrock
• Secret — where provider API keys should be stored