# Copyright (c) 2026 Cisco Systems, Inc. and its affiliates # SPDX-License-Identifier: Apache-2.0 $schema: "http://json-schema.org/draft-07/schema#" $id: "mas.config/config/v1" title: "config.yaml" description: > Project workspace configuration discovered by walking up from the current directory (or from MAS_WORKSPACE_ROOT). Secrets belong in the file named by mas_ctl.env (default .env) — never in this YAML. type: object additionalProperties: false properties: mas_ctl: type: object additionalProperties: false description: Defaults for mas-ctl chat / run-mas / validate. properties: flavour: type: string default: local description: >- Flavour name (library-standard bundle, e.g. local). Resolved to flavours/.yaml under the workspace or installed library. env: type: string default: .env description: Gitignored secrets file relative to workspace root. deployment: type: string description: Optional deployment manifest path (relative to workspace). runtime_id: type: string description: Kernel/runtime id override. runtime_profile: type: string description: Path to runtime-profile manifest (relative to workspace). cache: type: string enum: [read-only] description: >- Default cache mode for mas-ctl chat / serve. `read-only` answers from the recorded answers only (no LLM call, no cache write, no API key), like `--cache-read-only`. Omit it to call the model on a cache miss. trace: description: >- Human exchange log on stderr for mas-ctl chat / run-mas. `summary` (or `true`) is the usable default: headers + timestamps, untruncated AGENT→USER. `full` dumps payloads. `off` (or `false`) disables. Color is never implied; set trace_color or pass --trace-color. Machine data is events.jsonl / mas-lab telemetry, not this log. oneOf: - type: boolean - type: string enum: [off, summary, full] default: off trace_timestamps: type: boolean default: true description: UTC + elapsed on each exchange (on by default when tracing). trace_color: type: boolean default: false description: ANSI color on the exchange log. Never the CLI default. trace_engine: type: boolean default: false description: Include raw InvokeEngineIo / EngineIoReturn JSON. archive: type: object additionalProperties: false description: > Conversation archive (full session log). Complementary to traces/. Off by default so experiments at scale do not fill the disk. Enable only for reverse debugging / shallow checkpoints. properties: enabled: type: boolean default: false description: > Persist every archive chunk under traces/ when an events file is set. false keeps the archive in RAM only and forces deep checkpoints. dir_name: type: string default: archive description: Folder name colocated with events.jsonl (traces/archive). memory_watermark_bytes: type: integer minimum: 0 default: 67108864 description: > RAM cache cap after chunks are on disk. Folded leaves drop from memory past this watermark. 0 = keep every payload in RAM. mas_lab: type: object additionalProperties: false description: Defaults for mas-lab benchmark and demo commands. properties: flavour: type: string default: local benchmark_flavour: type: string description: Flavour used when running benchmark experiments. benchmark: type: object additionalProperties: false description: Defaults for ``mas-lab benchmark run`` stale-output handling. properties: clean_stale_outputs: type: boolean default: false description: >- When true, remove benchmark output folders for scenarios no longer declared in experiment.yaml before each run. clean_stale_trace_cache: type: boolean default: true description: >- When cleaning stale benchmark outputs, also remove trace-cache entries (data/cache/traces//) whose reference count reaches zero. labs_search_paths: oneOf: - type: string - type: array items: type: string description: >- Directories scanned for ``*.lab`` folders (relative to the config file, or absolute). An entry may itself be a ``*.lab`` directory. When this key is present (including an empty list) it is the exclusive lab catalog. When omitted, installed packages and cwd-walk stay additive. Separate from ``paths.labs_dir`` (benchmark output). New labs are created under the first entry. plugins: description: >- Workspace plugins (gdb, checkpoint stores). Off unless listed. The init template comments every catalog URN; uncomment ``plugins:`` and a line to enable it. Labs may enable the same URNs as ``lab.enable_plugins``. Specs that already name a plugin keep their own config. oneOf: - type: array items: type: string minLength: 1 - type: object additionalProperties: type: boolean infra_refs: oneOf: - type: string - type: array items: type: string description: >- Infra bundle refs merged left-to-right (e.g. standard:openai, standard:llm-proxy, or a workspace-relative LLMProxy path). Override at runtime with env var MAS_INFRA_REFS (comma- or space-separated) without editing this file; CLI --infra-ref still wins. runtime_refs: oneOf: - type: string - type: array items: type: string description: >- RuntimeEngine manifest refs merged left-to-right (e.g. standard:runtime-default or a workspace-relative path under runtime/). Omit entirely to use package defaults only. Override with env var MAS_RUNTIME_REFS (comma- or space-separated). infra_interceptors: oneOf: - type: string - type: array items: type: string description: Optional infra interceptor bundle refs. manifest_libraries: description: >- Extra library **search folders** for this workspace. Same scan as ``lab.libraries`` and ``MAS_LIBRARY_PATHS``: each path is a library root, or a parent of sibling library folders. ``library.yaml`` in those folders fills the catalog. Names come from the found directory stem. A legacy name→path map is flattened to its path values; it is not an alias table. oneOf: - type: array items: type: string minLength: 1 - type: object additionalProperties: type: string aliases: type: object additionalProperties: type: string description: >- Alias overrides for runtime plugin lookup. Keys are human-friendly names or legacy aliases; values are canonical plugin URNs such as mas.dp.react. defaults: type: object additionalProperties: false description: >- Overrides merged over mas-runtime's built-in defaults.yaml (per key, workspace value wins). See runtime/docs/agent-defaults.md. properties: model: type: string description: Fill-in LLM id for remaining Agent/MAS/experiment `any` after experiment.models (not written into committed specs). design_pattern: type: string description: Default plugin id for spec.design_pattern when manifests omit one. context_manager: type: string description: Default plugin id for spec.context_manager when manifests omit one. assembler: type: string description: Default plugin id for spec.assembler when manifests omit one. paths: type: object additionalProperties: false description: >- Optional path overrides (otherwise $XDG_CONFIG_HOME/mas/config.yaml paths or MAS_* env vars; see docs/user-config.md). properties: labs_dir: type: string description: Default root for benchmark run output (metadata.yaml, results.csv). cache_dir: type: string runs_dir: type: string archive_dir: type: string description: > Folder for the conversation archive after mas_ctl.archive.enabled is true. Setting this path does not turn persist on. Absolute paths win. Relative paths resolve from the app root. Not an agent spec field.