Configuration¶

OpenAI works with the built-in defaults after you set OPENAI_API_KEY; you do not need a config file for the standard first run. YAML files make changed model, workspace, agent, RAG, and MCP settings easy to reuse. URSA configs can be layered with environment variables and CLI flags, with commands to inspect the resulting configuration.

Prefer a user config¶

Put settings that should apply across projects in your platform's persistent user config. For example, this changes only the embedding model:

emb_model:
  model: openai:text-embedding-3-large

See Configuration files, CLI flags, and environment variables for user config paths and precedence. Use --config for a project-specific or one-off override, not as a requirement for ordinary OpenAI use.

Define reusable inference providers¶

Put endpoint and credential settings under inference_providers, then select a provider from each model. This keeps connection details in one place when chat and embedding models share an endpoint:

inference_providers:
  research_gateway:
    base_url: https://models.example.edu/v1
    api_key:
      env: RESEARCH_LLM_API_KEY
llm_model:
  model: openai:chat-model-name
  inference_provider: research_gateway
  max_completion_tokens: 10000
emb_model:
  model: openai:embedding-model-name
  inference_provider: research_gateway

The provider name is local to your configuration. A selected provider must exist, and model-specific values override values inherited from it. Keep secrets in environment references; put non-secret values such as base_url directly in the YAML file.

For ordinary OpenAI use, the built-in openai provider already supplies the endpoint. Set OPENAI_API_KEY and skip this configuration entirely.

Use this command to inspect the complete resolved configuration:

ursa --print-config

to inspect the full active configuration, including defaults and null values.

Common top-level settings¶

workspace: ./ursa-workspace
group: default
thread_id: null
use_web: false
tokens_before_summarize: 50000
llm_model:
  model: openai:gpt-5.4
emb_model: null
rag_tools: []
agent_config: {}
mcp_servers: {}

Model names normally use <provider>:<model-name>. See Models and inference providers for complete, tabbed examples covering OpenAI, OpenAI-compatible services, Anthropic, Google, Ollama, and Azure OpenAI.

`use_web` and `agent_config`¶

Use agent_config for per-agent options. Top-level use_web: true enables web tools for supported agents unless an agent overrides it:

use_web: true
agent_config:
  prompt:
    use_web: false

Summarization fallback¶

When a model's context limit is known, agents summarize at 70% of that limit. For unknown limits, set the fallback threshold in tokens using YAML:

tokens_before_summarize: 80000

Or use an environment variable or CLI flag:

URSA_TOKENS_BEFORE_SUMMARIZE=80000 ursa
ursa --tokens_before_summarize 80000

The value must be a positive integer and defaults to 50000. It sets the summarization trigger directly; the 70% calculation applies only to known model limits. The TUI's /status Config tab shows the effective threshold, with the configured fallback retained in a comment. Individual agents can override it through agent_config.<agent>.tokens_before_summarize.

In the dashboard, Settings → LLM → Summarization fallback (tokens) sets the fallback for new runs. Check saved model displays the effective threshold for the saved global or session model settings.

`workspace: tmp`¶

Set workspace: tmp to create a temporary workspace for the run. If a local directory named tmp already exists, URSA uses that directory.