CUGA LogoCUGA AGENT
Configure

Settings Reference

Complete reference for all CUGA configuration options in settings.toml

This document provides comprehensive reference for all configuration options available in ./src/cuga/settings.toml.

File Location

./src/cuga/settings.toml

This is the main configuration file controlling all CUGA behavior.

Configuration Sections

Page Understanding

Controls how CUGA analyzes and understands web pages.

[page_understanding]
transformer_path = "cuga.backend.browser_env.page_understanding.pu_transform.PageUnderstandingV1"
demo_nocodeui_pu = false

Options

OptionTypeDefaultDescription
transformer_pathStringPageUnderstandingV1Python path to page understanding transformer. Handles DOM analysis and page content extraction.
demo_nocodeui_puBooleanfalseDisable page understanding for demo no-code UI. Set to true to skip page understanding in no-code scenarios.

Evaluation

Controls evaluation and testing behavior.

[evaluation]
max_steps = 55

Options

OptionTypeDefaultDescription
max_stepsInteger55Maximum number of execution steps allowed before stopping. Prevents infinite loops and runaway execution. Higher values allow more complex tasks.

Demo Mode

Controls demo mode behavior and starting state.

[demo_mode]
start_url = "https://opensource-demo.orangehrmlive.com/web/index.php/auth/login"

Options

OptionTypeDefaultDescription
start_urlStringOrangeHRM demo URLStarting URL for web/hybrid modes. Browser opens to this page when demo starts. Change to test different applications.

Features

Core feature configuration.

[features]
cuga_mode = "balanced"

Options

OptionTypeDefaultDescription
cuga_modeString"balanced"Execution reasoning mode. Options: "fast", "balanced", "accurate", "save_reuse_fast", "custom". Fast is quicker but less accurate; Accurate is slower but more precise; Save & Reuse caches workflows.

Note: The legacy memory_provider key (mem0) was removed from CUGA classic in cuga-agent PR #153. Current Memory is Build → Memory.


Advanced Features

Advanced configuration flags for specialized behavior.

[advanced_features]
# Benchmark and Evaluation
web_arena_eval = false
benchmark = "default"
appworld_final_answer_plain = true

# Vision and Analysis
use_vision = true
use_paraphrase = false

# Tracing and Debugging
tracker_enabled = false
langfuse_tracing = false

# Integrations
wxo_integration = false
use_location_resolver = false

# Execution Modes
mode = 'api'
use_extension = false

# Planning and Optimization
reflection_enabled = false
pre_execute_verify_enabled = false
# pre_execute_verify_timeout = 60
shortlisting_tool_threshold = 35
cuga_lite_enable_few_shots = true
cuga_lite_max_steps = 70
cuga_lite_bind_tools_mode = "none"
cuga_lite_bind_tools_apps = []
cuga_lite_bind_tools_include_find_tools = false
cuga_lite_nl_auto_continue = false
enable_todos = false

# Workflows
save_reuse_generate_html = false

# E2B Cloud Sandbox
e2b_sandbox = false
e2b_sandbox_mode = "per-session"
e2b_sandbox_idle_ttl = 600
e2b_sandbox_max_age = 86400
e2b_sandbox_ttl_buffer = 60
e2b_cleanup_on_create = true
e2b_cleanup_frequency = 0

# Variable Lifecycle
sub_task_keep_last_n = 5
code_executor_keep_last_n = -1

# Limits & Timeouts
message_window_limit = 100
max_input_length = 5000
tool_call_timeout = 30
execution_output_max_length = 70000

# Misc
path_segment_index = 1
force_autonomous_mode = false

Benchmark & Evaluation Options

OptionTypeDefaultDescription
web_arena_evalBooleanfalseEnable WebArena benchmark evaluation mode. For testing on WebArena benchmark suite.
benchmarkString"default"Benchmark mode. Options: "default", "appworld", "webarena". Controls evaluation settings.
appworld_final_answer_plainBooleantrueWhen benchmark = "appworld", use plain answer: completion prompts (no JSON) for final formatting.

Vision & Analysis Options

OptionTypeDefaultDescription
use_visionBooleantrueEnable vision capabilities for analyzing screenshots and visual page content. Enhances page understanding.
use_paraphraseBooleanfalseParaphrase user inputs for better interpretation. Can improve understanding of ambiguous queries.

Tracing & Debugging Options

OptionTypeDefaultDescription
tracker_enabledBooleanfalseEnable activity tracking and detailed execution logs. Useful for debugging and analysis.
langfuse_tracingBooleanfalseEnable Langfuse integration for comprehensive execution tracing and monitoring. Requires Langfuse account.

Integration Options

OptionTypeDefaultDescription
wxo_integrationBooleanfalseEnable IBM WatsonX Orchestrate integration. For enterprise IBM customers.
use_location_resolverBooleanfalseEnable location resolution for geographic context. Helps when tasks involve location-based data.

Execution Mode Options

OptionTypeDefaultDescription
modeString'api'Task execution mode. Options: 'api', 'web', 'hybrid'. API mode uses tools only; Web mode uses browser; Hybrid uses both. See Task Modes for details.
use_extensionBooleanfalseEnable browser extension for web/hybrid modes. Required for web and hybrid execution.

Planning & Optimization Options

The former full CugaAgent graph is retired. lite_mode, lite_mode_tool_threshold, force_lite_mode_apps, code_planner_enabled, api_planner_hitl, and decomposition_strategy are not current routing/planner controls. API/tool tasks use CugaLite. CugaAgent remains the public SDK class.

OptionTypeDefaultDescription
pre_execute_verify_enabledBooleanfalseAdvisory VERIFY check before mutating code blocks; independent of reflection.
pre_execute_verify_timeoutFloat (seconds)60VERIFY timeout; errors/timeouts allow execution. Env: DYNACONF_ADVANCED_FEATURES__PRE_EXECUTE_VERIFY_TIMEOUT.
reflection_enabledBooleanfalseExtra reflection pass after a step. See Todos, reflection, shortlisting.
shortlisting_tool_thresholdInteger35If total tools exceed this, enable find_tools (configured shortlister). See shortlisting.
enable_todosBooleanfalseChecklist tool for multi-step tasks. See Todos.
cuga_lite_enable_few_shotsBooleantrueMCP few-shots: prompt block + few-shot chat prefix in CugaLite. Set false to disable.
cuga_lite_max_stepsInteger70Maximum number of steps (call_model + sandbox cycles) in CugaLite before returning an error.
cuga_lite_bind_tools_modeString"none"How CugaLite binds tools to the model. Options: "none", "all", "apps". (Per-model overrides live in model_runtime_profile.py.)
cuga_lite_bind_tools_appsArray<String>[]When cuga_lite_bind_tools_mode = "apps", list of app names to bind (e.g. ["crm", "slack"]).
cuga_lite_bind_tools_include_find_toolsBooleanfalseWhen binding tools, also bind the find_tools StructuredTool alongside all/apps.
cuga_lite_nl_auto_continueBooleanfalseWhen the model returns NL with no code, classify interim vs final; if interim, simulate a user continue and re-call the model.
run_receiptBooleanfalseAttach a per-run token/timing receipt to InvokeResult. No overhead when off.
enable_filesystem_toolsBooleanfalseEnable workspace filesystem tools (read_file, write_file, …).
enable_shell_toolBooleanfalseEnable shell-style tools (run_command, …). Required for most agent skills.
opensandbox_sandboxBooleantrueUse OpenSandbox (Docker) for code execution. Requires Docker + uv sync --extra opensandbox.
sandbox_modeString"native"Shell sandbox: "native" (macOS sandbox-exec; falls back to local elsewhere), "opensandbox", "e2b", or "local".
sandbox_execution_timeoutInteger (seconds)30Per-block wall clock for sandbox code execution.
max_tool_calls_per_runInteger256Max tool calls per user turn. 0 disables.
max_tool_calls_per_blockInteger100Max tool calls in one generated code block (recoverable). 0 disables.
max_tool_calls_per_threadInteger2000Max tool calls per conversation (never reset). 0 disables.
cuga_lite_bind_tools_tool_namesArray<String>[]When bind mode is tools or apps_and_tools, tool names to bind.
cuga_lite_bind_tools_max_countInteger128Cap on tools sent to bind_tools. 0 disables. Over-cap uses a shortlister.
cuga_lite_bind_tools_pad_to_capBooleanfalsePad shortlister output to fill the cap.
cuga_lite_warn_suspect_argsBooleantrueWarn (never coerce) when a tool argument looks malformed for its schema.
cuga_lite_blocked_claim_retryBooleantrueRetry once if the model claims tools are unavailable but none have run.
strip_harmony_control_tokensString / Boolean"auto"Strip gpt-oss harmony tokens from the final answer. "auto" only for harmony models.
variables_summary_max_lengthInteger12000Cap on the “Available Variables” prompt addendum.

Workflow Options

OptionTypeDefaultDescription
save_reuse_generate_htmlBooleanfalseGenerate HTML visualization for saved workflows. Creates interactive diagrams of workflow execution. Disabled by default for performance.

E2B Cloud Sandbox Options

See E2B Cloud Sandbox for detailed E2B configuration.

OptionTypeDefaultDescription
e2b_sandboxBooleanfalseEnable E2B cloud sandbox for code execution. Requires E2B account and API key.
e2b_sandbox_modeString"per-session"E2B sandbox lifecycle. Options: "per-session" (cached per thread), "single" (shared sandbox), "per-call" (new sandbox each call).
e2b_sandbox_idle_ttlInteger600Idle timeout in seconds before sandbox expires. Default: 10 minutes. Shorter values save cost.
e2b_sandbox_max_ageInteger86400Max age for "single" mode sandboxes in seconds. Default: 24 hours. Set to 0 to disable age-based recreation.
e2b_sandbox_ttl_bufferInteger60Safety buffer in seconds before E2B timeout. Allows graceful shutdown.
e2b_cleanup_on_createBooleantrueRun cleanup when creating new sandboxes. Prevents sandbox accumulation.
e2b_cleanup_frequencyInteger0Check all sandboxes every N get_or_create calls. 0 = only on create. Higher values reduce cleanup overhead.

Variable Lifecycle Options

OptionTypeDefaultDescription
sub_task_keep_last_nInteger5Number of most recent generated variables to keep when executing sub-tasks.
code_executor_keep_last_nInteger-1Variables retained after code execution. -1 keeps all; positive integers keep the last N.

Limit & Timeout Options

OptionTypeDefaultDescription
message_window_limitInteger100Maximum messages to keep in conversation history. Older messages discarded when exceeded. Reduces context size.
max_input_lengthInteger5000Maximum character length for user input. Prevents abuse and excessive processing.
tool_call_timeoutInteger (seconds)30Timeout for tool/API calls (sandbox operations). Raises TimeoutError when exceeded.
execution_output_max_lengthInteger70000Maximum characters returned in execution output. Prevents token overflow on very large tool responses.

Misc Options

OptionTypeDefaultDescription
path_segment_indexInteger1Which path segment to use for OpenAPI operation naming (1 = first, 2 = second, etc.).
force_autonomous_modeBooleanfalseForce fully autonomous execution (no HITL prompts) regardless of other settings.

Server Ports

Controls service ports and URLs for all CUGA services.

[server_ports]
registry = 8001
demo = 7860
demo_server_startup_max_retries = 420
apis_url = 9000
crm_api = 8007
saved_flows = 8003
environment_url = 8000
filesystem_mcp = 8112
docs_mcp = 8113
digital_sales_api = 8000
mcp_server = 8000
petstore_api = 8081
graph_visualization = 8080
orchestrate_url = 4321
trm_url = 8080
oak_health_api = 8090

Options

OptionTypeDefaultDescription
registryInteger8001API registry service port. Where CUGA tools and APIs are exposed.
demoInteger7860CUGA demo interface port. Open browser to http://localhost:7860
demo_server_startup_max_retriesInteger420CLI cuga start polls the demo Uvicorn process every ~0.5s up to this many times before timing out (default ≈ 3 minutes).
apis_urlInteger9000APIs service port. (Rarely used)
crm_apiInteger8007CRM demo application port. Used in cuga start demo_crm.
saved_flowsInteger8003Saved workflows service port. For Save & Reuse feature.
environment_urlInteger8000Environment service port. Base configuration service.
filesystem_mcpInteger8112Filesystem MCP server port. Used in the Filesystem MCP demo.
docs_mcpInteger8113Docs MCP server port.
digital_sales_apiInteger8000Digital Sales API port. Used in digital sales demo.
mcp_serverInteger8000MCP server port for tool integration.
petstore_apiInteger8081Petstore demo API port. Example API for testing.
graph_visualizationInteger8080Graph visualization service port. For execution flow visualization.
orchestrate_urlInteger4321Orchestration service port. (Enterprise only)
trm_urlInteger8080Task/Routing/Management URL port. (Advanced)
oak_health_apiInteger8090cuga-oak-health OpenAPI port. Used by cuga start demo_health.

Note: The memory = 8888 port has been removed. Memory support for CUGA classic was deprecated in cuga-agent PR #153.

Advanced Port Configuration

For E2B cloud sandbox, configure registry exposure:

[server_ports]
# registry_host = "http://localhost:8001"  # Optional: Full registry URL
# function_call_host = ""  # Optional: For E2B to call functions via ngrok
OptionTypeDefaultDescription
registry_hostString(optional)Full registry URL. Falls back to "http://localhost:{registry}" if not set.
function_call_hostString(optional)URL for E2B or external systems to call functions. Usually an ngrok URL. Falls back to registry_host, then default localhost:8001.

Supervisor

Configures the multi-agent supervisor when running CUGA as a server. SDK-only usage (building a CugaSupervisor in Python) does not require this section.

[supervisor]
enabled = false
config_path = "src/cuga/backend/tools_env/registry/config/supervisor_demo_crm.yaml"
agent_approval = true
pass_variables_a2a = false
OptionTypeDefaultDescription
enabledBooleanfalseEnable CugaSupervisor in the server. See CugaSupervisor SDK doc.
config_pathString""Path to the supervisor YAML config. If empty, uses the default supervisor setup.
agent_approvalBooleantrueRequire user approval before delegating to any sub-agent (human-in-the-loop).
pass_variables_a2aBooleanfalseWhen true, the A2A delegate tool accepts variables and sends them in request metadata (A2A protocol extension).

The bundled multi-agent demo can be launched with:

cuga start demo_supervisor

Shortlister

[shortlister] selects llm (default), embedding, hybrid, or a dotted custom class path. It supports fallback_strategy, threshold, top_k, max_results, min_score, query_weight, embedding_provider, and embedding_model. [shortlister.discovery] and [shortlister.bind_cap] override individual seams. See shortlisting strategies for defaults and examples.

Final answer

[final_answer]
instructions = ""
function = ""

instructions guides the separate answer composer; CugaLite uses special_instructions (SDK final_answer="..." sets this). function is a trusted dotted (str) -> str callable applied to the delivered answer. See Final answer for execution order, fallback, and scope limitations.

Agent spawn

Opt-in nested sub-agents. Off by default — no prompt or tool overhead until you enable it.

[agent_spawn]
enabled = false
max_spawn_depth = 2
forward_sync_subagent_events = true
OptionTypeDefaultDescription
enabledBooleanfalseAllow spawn_agent / get_agent_result.
max_spawn_depthInteger2How deep nested spawns may go.
forward_sync_subagent_eventsBooleantrueForward sub-agent events to the parent stream.

See CugaAgent — sub-agent spawn.


Storage

Selects the backend for policy vectors, knowledge vectors, and knowledge metadata.

[storage]
mode = "local"
local_db_path = ""
postgres_url = ""

[storage.embedding]
provider = "local"
model = "BAAI/bge-small-en-v1.5"
dim = 384
base_url = ""
api_key = ""

Storage modes

Datalocalprod
Policy vectorssqlite-vec at [policy].policy_db_path or storage.local_db_path (defaults to DBS_DIR/cuga.db)storage.postgres_url (pgvector)
Knowledge vectors{knowledge.persist_dir}/knowledge_vectors.db (vec0 tables per collection)storage.postgres_url
Knowledge metadata{knowledge.persist_dir}/metadata.dbPostgres tables cuga_knowledge_meta_* (uploaded files stay under persist_dir/files/)

DBS_DIR defaults to the package dbs/ directory or the value of the CUGA_DBS_DIR env var.

[storage] options

OptionTypeDefaultDescription
modeString"local""local" (sqlite/sqlite-vec) or "prod" (Postgres + pgvector).
local_db_pathString""Override path for the local SQLite DB. Empty = DBS_DIR/cuga.db.
postgres_urlString""Postgres connection URL. Required when mode = "prod".
preserve_configs_on_startupString"prod"Skip demo/manager config seed when agent configs already exist. "prod", "local", or "any".

[storage.embedding] options

OptionTypeDefaultDescription
providerString"local""openai", "local", or "auto" (tries OpenAI, falls back to local).
modelString"BAAI/bge-small-en-v1.5"Embedding model name.
dimInteger384Embedding dimension. 1536 for OpenAI, 384 for BAAI/bge-small-en-v1.5.
base_urlString""Optional custom endpoint for an OpenAI-compatible embedding service.
api_keyString""Optional API key for the embedding endpoint. Falls back to OPENAI_API_KEY.

Policy

Configures the policy system.

[policy]
enabled = true
collection_name = "cuga_policies"
policy_db_path = ""
playbook_refine = false
filesystem_sync = true
cuga_folder = ".cuga"
auto_load_policies = true
OptionTypeDefaultDescription
enabledBooleantrueEnable the policy system (intent guards, playbooks, tool guides, ToolGuard, tool approvals, output formatters).
collection_nameString"cuga_policies"Vector store collection name for policies.
policy_db_pathString""Optional explicit path for the policy DB. When empty, uses storage.local_db_path.
playbook_refineBooleanfalseEnable playbook refinement based on user progress (requires an LLM call).
filesystem_syncBooleantrueSync policies to/from the .cuga folder on disk.
cuga_folderString".cuga"Path to the .cuga folder used for policy files.
auto_load_policiesBooleantrueAutomatically load policies from the .cuga folder on startup.

Skills

Agent skills (SKILL.md). See Agent skills.

[skills]
enabled = false
root = "cuga"
opensandbox_image = "opensandbox/code-interpreter:v1.0.2"
opensandbox_entrypoint = "/opt/opensandbox/code-interpreter.sh"
opensandbox_python_version = "3.11"
opensandbox_domain = "localhost:8080"
opensandbox_timeout_seconds = 600
OptionTypeDefaultDescription
enabledBooleanfalseDiscover skills, expose load_skill, and enable /api/skills.
rootString"cuga"Single skills directory: cuga (.cuga/skills), agents, global_agents, or global_cuga.
opensandbox_imageString"opensandbox/code-interpreter:v1.0.2"Docker image when sandbox_mode = "opensandbox".
opensandbox_entrypointString"/opt/opensandbox/code-interpreter.sh"Entrypoint inside that image.
opensandbox_python_versionString"3.11"Python version injected into the image.
opensandbox_domainString"localhost:8080"OpenSandbox server. Override with OPEN_SANDBOX_DOMAIN.
opensandbox_timeout_secondsInteger600Sandbox lifetime in seconds.

A2A

Expose CUGA over the Agent-to-Agent protocol. Off by default — the A2A package is not imported until you enable it.

[a2a]
enabled = false
agent_name = "cuga"
agent_description = "CUGA agent exposed over A2A."
agent_version = "0.0.0"
agent_url = "http://localhost:8000"
auth_required = false
skill_ids = ["delegate_task"]
supervisor_config_path = ""
auto_approve = false
OptionTypeDefaultDescription
enabledBooleanfalseMount the A2A router.
agent_nameString"cuga"Name on the AgentCard.
agent_descriptionString"CUGA agent exposed over A2A."AgentCard description.
agent_versionString"0.0.0"AgentCard version.
agent_urlString"http://localhost:8000"Public URL clients should call.
auth_requiredBooleanfalseAdvertise a bearer security scheme on the AgentCard.
skill_idsArray<String>["delegate_task"]Skills listed on the AgentCard.
supervisor_config_pathString""YAML for the supervisor that handles inbound A2A. Empty = placeholder runner.
auto_approveBooleanfalseSimple runner only: auto-confirm HITL interrupts.

Service

Identifies the running CUGA instance, useful for multi-tenant or Kubernetes deployments.

[service]
instance_id = ""
tenant_id = ""
OptionTypeDefaultDescription
instance_idString""Override with DYNACONF_SERVICE__INSTANCE_ID (e.g. K8s pod name, deployment id).
tenant_idString""Multi-tenant SaaS tenant id. Override with DYNACONF_SERVICE__TENANT_ID.

Secrets

Selects how CUGA resolves secrets at runtime — local environment variables or HashiCorp Vault.

[secrets]
mode = "local"
force_env = true
db_encryption_key_env = "CUGA_SECRET_KEY"
vault_addr = ""
vault_token_env = "VAULT_TOKEN"
vault_auth_method = ""
vault_k8s_role = ""
vault_k8s_mount_path = "kubernetes"
vault_k8s_jwt_path = "/var/run/secrets/kubernetes.io/serviceaccount/token"
vault_cacert = ""
vault_skip_verify = false
vault_mount = "secret"
vault_kv_version = ""
vault_secret_path = ""
vault_write_enabled = false
aws_region = ""
OptionTypeDefaultDescription
modeString"local""local" (env vars / UI overrides) or "vault".
force_envBooleantrueIf true, always resolve from os.environ (ignores UI overrides and Vault).
db_encryption_key_envString"CUGA_SECRET_KEY"Environment variable holding the encryption key for stored secrets.
vault_addrString""Vault server URL (e.g. https://vault.example.com:8200).
vault_token_envString"VAULT_TOKEN"Env var name that holds the Vault token (when vault_auth_method = "token").
vault_auth_methodString"""", "token", or "kubernetes". Override with DYNACONF_SECRETS__VAULT_AUTH_METHOD.
vault_k8s_roleString""Vault role used by Kubernetes auth.
vault_k8s_mount_pathString"kubernetes"Mount path of the Kubernetes auth backend.
vault_k8s_jwt_pathString/var/run/.../tokenPath to the service-account JWT inside the pod.
vault_cacertString""Path to a PEM bundle used to verify Vault TLS (env: VAULT_CACERT).
vault_skip_verifyBooleanfalseDev only — disable TLS verification (env: VAULT_SKIP_VERIFY).
vault_mountString"secret"KV mount path within Vault.
vault_kv_versionString"""1" or "2". Empty defaults to KV v2; use "1" only for KV v1 mounts.
vault_secret_pathString""Base path for secrets. Override with DYNACONF_SECRETS__VAULT_SECRET_PATH.
vault_write_enabledBooleanfalseAllow CUGA to write secrets back to Vault (most setups should leave this off).
aws_regionString""Reserved for AWS Secrets Manager integration.

Auth

Optional OIDC/BFF authentication for the CUGA server.

[auth]
enabled = false
authorization_enabled = false
manage_roles = ["ServiceOwner", "ServiceAdmin"]
chat_roles = ["ServiceOwner", "ServiceAdmin", "ServiceUser"]
session_cookie_name = "cuga_session"
session_max_age = 3600
jwks_cache_ttl = 3600
require_https = false
ssl_keyfile = ""
ssl_certfile = ""
iam_proxy_url = ""
iam_proxy_skip_verify = false
iam_proxy_ca_bundle = ""
role_token_source = "auto"
OptionTypeDefaultDescription
enabledBooleanfalseEnable OIDC/BFF authentication on the demo server.
authorization_enabledBooleanfalseEnforce role-based authorization in addition to authentication.
manage_rolesArray<String>["ServiceOwner", "ServiceAdmin"]Roles allowed to manage policies, tools, and configuration.
chat_rolesArray<String>["ServiceOwner", "ServiceAdmin", "ServiceUser"]Roles allowed to chat with the agent.
session_cookie_nameString"cuga_session"Name of the BFF session cookie.
session_max_ageInteger (seconds)3600Session lifetime.
jwks_cache_ttlInteger (seconds)3600How long signed-key sets from the IdP are cached.
require_httpsBooleanfalseReject non-HTTPS traffic (production).
ssl_keyfileString""Path to TLS private key (when terminating TLS in CUGA).
ssl_certfileString""Path to TLS certificate.
iam_proxy_urlString""URL of an upstream IAM proxy in front of CUGA.
iam_proxy_skip_verifyBooleanfalseSkip TLS verification against the IAM proxy (dev only).
iam_proxy_ca_bundleString""PEM bundle for IAM-proxy TLS (independent of oidc_ca_bundle).
role_token_sourceString"auto"Where roles come from: "auto", "id_token", "access_token", "iam_proxy".

OIDC client/issuer/secret values are configured via environment variables — see Environment Variable Overrides.


UI

Customize the demo UI branding.

[ui]
hide_cuga_logo = false
brand_name = "CUGA Agent"
OptionTypeDefaultDescription
hide_cuga_logoBooleanfalseHide the CUGA logo in the header (e.g. when white-labelling).
brand_nameString"CUGA Agent"App name shown in the header.

Context Summarization

Automatically summarize older parts of the conversation when the context window starts to fill up.

[context_summarization]
enabled = false
keep_last_n_messages = 10
trim_tokens_to_summarize = 500
summarization_model = "gpt-4o-mini"
trigger_fraction = 0.75
# trigger_tokens = 2000
# trigger_messages = 20
# custom_summary_prompt = "Provide a concise summary of the conversation: {messages}"
OptionTypeDefaultDescription
enabledBooleanfalseEnable intelligent context summarization.
keep_last_n_messagesInteger10Number of recent messages preserved unsummarized.
trim_tokens_to_summarizeInteger500Target token count for generated summaries.
summarization_modelString"gpt-4o-mini"Model used to generate summaries (kept fast and cheap by default).
trigger_fractionFloat0.75Trigger summarization at this fraction of the model's context window.
trigger_tokensInteger(unset)Alternative trigger: total tokens above this count.
trigger_messagesInteger(unset)Alternative trigger: number of messages since the last summary.
custom_summary_promptString(unset)Optional custom prompt template (uses LangChain default if not set).

Connections

Controls TLS for outbound LLM inference connections.

[connections]
inference_ca_cert = ""
inference_disable_ssl = false
llm_http_timeout = 61
OptionTypeDefaultDescription
inference_ca_certString""Path to a CA certificate for the inference HTTP clients (OpenAI and LiteLLM). Env: CUGA_INFERENCE_CA_CERT.
inference_disable_sslBooleanfalseDisable SSL verification for all inference connections (overrides inference_ca_cert). Env: CUGA_DISABLE_SSL.
llm_http_timeoutInteger (seconds)61HTTP timeout for OpenAI / Azure / OpenRouter clients. Env: CUGA_LLM_HTTP_TIMEOUT.

Observability

Optional OpenLit / OpenTelemetry observability for LLM calls. Langfuse and cuga-viz are separate — see Observability.

[observability]
openlit = false
pricing_json = ""
litellm_local_model_cost_map = true
OptionTypeDefaultDescription
openlitBooleanfalseEnable OpenLit LLM observability via OpenTelemetry (OTLP). Requires pip install cuga[observability]. Configure the OTLP endpoint via OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318.
pricing_jsonString""Local OpenLit pricing.json for airgapped environments. Empty = bundled asset.
litellm_local_model_cost_mapBooleantruePrefer LiteLLM's bundled model cost map (avoids a GitHub fetch).

A local testing stack (OTel Collector + Tempo + Prometheus + Grafana) is provided under deployment/docker-compose/openlit/ in the cuga-agent repo.


Memory

Settings for the Memory capability (trajectory learning). The TOML section is still named [evolve] — that is the backend, not a separate product. See Memory.

Optional integration with altk-evolve for CugaLite.

[evolve]
enabled = true
url = "http://127.0.0.1:8201/sse"
mode = "auto"
app_name = "evolve"
lite_mode_only = true
save_on_success = true
save_on_failure = true
async_save = true
timeout = 30.0
OptionTypeDefaultDescription
enabledBooleantrueMaster toggle for Evolve integration.
urlString"http://127.0.0.1:8201/sse"SSE endpoint of a manually-run Evolve MCP server (used when mode = "direct" or as a fallback in "auto").
modeString"auto""auto" = registry first then direct SSE fallback; "registry" = registry only; "direct" = direct SSE only.
app_nameString"evolve"MCP app/server name when Evolve is managed by the CUGA registry.
lite_mode_onlyBooleantrueOnly activate Evolve for CugaLite mode.
save_on_successBooleantrueSave trajectory on successful task completion.
save_on_failureBooleantrueSave trajectory on failed task completion.
async_saveBooleantrueSave trajectories in the background (non-blocking).
timeoutFloat (seconds)30.0Timeout for Evolve MCP calls.

Configuration Examples

Fast Development Setup

[features]
cuga_mode = "fast"

[advanced_features]
use_vision = true
mode = 'api'

[server_ports]
demo = 7860
registry = 8001

Production Enterprise Setup

[features]
cuga_mode = "accurate"

[advanced_features]
use_vision = true
langfuse_tracing = true          # Full observability
mode = 'api'
message_window_limit = 200
max_input_length = 10000

[auth]
enabled = true
authorization_enabled = true
require_https = true

[secrets]
mode = "vault"
vault_addr = "https://vault.example.com:8200"
vault_auth_method = "kubernetes"
vault_k8s_role = "cuga"

[storage]
mode = "prod"
postgres_url = "postgresql+psycopg://user:pass@db:5432/cuga"

[observability]
openlit = true                   # OTLP-based tracing

[server_ports]
demo = 7860
registry = 8001

E2B Cloud Execution Setup

[features]
cuga_mode = "balanced"

[advanced_features]
e2b_sandbox = true
e2b_sandbox_mode = "per-session"
e2b_sandbox_idle_ttl = 600
use_vision = true

[server_ports]
demo = 7860
registry = 8001
function_call_host = "https://your-ngrok-url.ngrok.io"  # E2B tunnel URL

Web/Hybrid Mode Setup

[demo_mode]
start_url = "https://example.com"

[features]
cuga_mode = "balanced"

[advanced_features]
mode = 'hybrid'                    # or 'web' for web-only
use_extension = true
use_vision = true

[server_ports]
demo = 7860
registry = 8001

Environment Variable Overrides

Many settings can be overridden via environment variables. The priority is:

  1. Environment Variables (highest - overrides everything)
  2. settings.toml (middle - configuration file)
  3. Code Defaults (lowest - hardcoded defaults)

Environment Variables Reference

All environment variables that can be used to configure CUGA:

LLM Provider Configuration

VariableDescriptionExample
AGENT_SETTING_CONFIGLLM settings file to usesettings.openai.toml
MODEL_NAMEOverride default model namegpt-4o
OPENAI_API_KEYOpenAI API keysk-...
OPENAI_BASE_URLCustom OpenAI-compatible endpoint (for LiteLLM)http://localhost:4000
OPENAI_API_VERSIONOpenAI API version2024-08-01-preview
AZURE_OPENAI_API_KEYAzure OpenAI API key
AZURE_OPENAI_ENDPOINTAzure OpenAI endpoint URL
WATSONX_PROJECT_IDWatsonX project ID
WATSONX_URLWatsonX endpoint URLhttps://us-south.ml.cloud.ibm.com
WATSONX_APIKEYWatsonX API key
GROQ_API_KEYGroq API key
OPENROUTER_API_KEYOpenRouter API key
OPENROUTER_BASE_URLOpenRouter base URLhttps://openrouter.ai/api/v1
RITS_API_KEYRITS API key (IBM internal)

Cloud Sandbox (E2B)

VariableDescriptionExample
E2B_API_KEYE2B API key for cloud sandboxe2b_...

Browser Configuration

VariableDescriptionExample
MAC_USER_DATA_PATHChrome profile path on macOS~/Library/Application Support/Google/Chrome/AgentS
WINDOWS_USER_DATA_PATHChrome profile path on WindowsC:/Users/<User>/AppData/Local/Google/Chrome/User Data/AgentS

Secrets & Vault

VariableDescriptionExample
CUGA_SECRET_KEYEncryption key for secrets stored by CUGA (matches [secrets].db_encryption_key_env).
VAULT_TOKENVault token (when vault_auth_method = "token").
VAULT_CACERTPath to PEM bundle for Vault TLS.
VAULT_SKIP_VERIFYDisable Vault TLS verification (dev only).true
DYNACONF_SECRETS__VAULT_AUTH_METHODOverride [secrets].vault_auth_method at runtime.kubernetes
DYNACONF_SECRETS__VAULT_SECRET_PATHOverride [secrets].vault_secret_path.

Authentication (OIDC / BFF)

VariableDescription
OIDC_ISSUEROIDC issuer URL.
OIDC_CLIENT_IDOIDC client id.
OIDC_CLIENT_SECRETOIDC client secret.
OIDC_REDIRECT_URICallback URL registered with the IdP.
OIDC_CA_BUNDLEOptional CA bundle for OIDC TLS (independent of iam_proxy_ca_bundle).

Service Identity

VariableDescription
DYNACONF_SERVICE__INSTANCE_IDOverride [service].instance_id (e.g. K8s pod name).
DYNACONF_SERVICE__TENANT_IDOverride [service].tenant_id for multi-tenant deployments.

TLS for Inference

VariableDescription
CUGA_INFERENCE_CA_CERTCA cert for OpenAI/LiteLLM HTTP clients (overrides [connections].inference_ca_cert).
CUGA_DISABLE_SSLDisable TLS verification for all inference connections (overrides inference_disable_ssl).

Storage

VariableDescription
CUGA_DBS_DIROverride DBS_DIR (default location for the local SQLite policy DB).

Observability

VariableDescriptionExample
OTEL_EXPORTER_OTLP_ENDPOINTOTLP collector endpoint when [observability].openlit = true.http://localhost:4318

Server Ports (Dynaconf)

Use DYNACONF_SERVER_PORTS__<NAME> to override port settings:

VariableDescriptionDefault
DYNACONF_SERVER_PORTS__REGISTRYAPI registry port8001
DYNACONF_SERVER_PORTS__DEMODemo UI port7860
DYNACONF_SERVER_PORTS__CRM_APICRM demo API port8007
DYNACONF_SERVER_PORTS__EMAIL_MCPEmail MCP server port8000
DYNACONF_SERVER_PORTS__EMAIL_SINKEmail SMTP sink port1025
DYNACONF_SERVER_PORTS__FILESYSTEM_MCPFile System MCP port8112
DYNACONF_SERVER_PORTS__DOCS_MCPDocs MCP port8113
DYNACONF_SERVER_PORTS__OAK_HEALTH_APIHealth-demo OpenAPI port8090

Example .env File

# LLM Provider (choose one)
AGENT_SETTING_CONFIG="settings.openai.toml"
OPENAI_API_KEY="sk-..."

# Optional: E2B Cloud Sandbox
E2B_API_KEY="e2b_..."

# Optional: Chrome profile for demo mode
MAC_USER_DATA_PATH="~/Library/Application Support/Google/Chrome/AgentS"

See Model Configuration for detailed LLM setup instructions.


Troubleshooting

Port Already in Use

Problem: "Address already in use" error for demo port

Solution:

[server_ports]
demo = 7861  # Change to different port

Or kill existing process:

lsof -i :7860
kill -9 <PID>

Settings Not Taking Effect

Problem: Configuration changes don't apply after restart

Solutions:

  1. Ensure you edited the correct file: ./src/cuga/settings.toml
  2. Check for syntax errors in TOML (invalid indentation, missing quotes)
  3. Restart CUGA completely (kill all processes)
  4. Check environment variables aren't overriding (run env | grep CUGA)

Mode/Feature Not Available

Problem: Feature appears disabled despite being in settings

Solutions:

  1. Check dependencies are installed: uv sync --group <feature>
  2. Verify feature is enabled: grep <feature> settings.toml
  3. Check required environment variables are set
  4. Review logs for initialization errors

Performance Issues

Optimization Strategy:

  1. Tune shortlisting for large tool catalogs
  2. Reduce message_window_limit to 50 to keep prompts small
  3. Disable langfuse_tracing unless needed
  4. Use fast mode if accuracy isn't critical

Next Steps

Resources