Skip to main content

Configuration

Anyy reads a single YAML configuration file and layers it on top of built-in defaults. This page explains the configuration model: where settings live, how the file is found, and the order in which values are resolved.

It does not list every key. For the exhaustive tables, see the configuration reference and the environment variables reference. To create or edit configuration interactively, use the setup wizard. For provider and model fields specifically, see Configuring Models and the provider configuration reference.

Directory Layout​

All of an installation's state lives under a single home directory — ~/.anyy for a normal-user install, /root/.anyy when running as root. The configuration file is always config.yaml at the root of the home directory:

<home>/
  config.yaml      # the configuration file (this page)
  secrets/         # resolved secret material (env:/file:/secret: backends)
  memory/          # MEMORY.md, USER.md, and memory state
  state.db         # sessions, messages, approvals, jobs, audit, runtime state
  raw/             # per-session JSONL mirrors for inspection/recovery
  skills/          # installed skills
  anyy.sock   # gateway Unix socket
  logs/  cache/  workspace/  backups/  channels/  ...

The home directory is resolved in this order:

  1. The --home PATH flag, when passed to a command.
  2. The ANYY_HOME environment variable.
  3. The default — ~/.anyy for a normal-user install, /root/.anyy when running as root (/root/.anyy is the built-in fallback used when no home is otherwise resolved).

Run anyy config to print the resolved paths and current settings for the active home. It is read-only.

Configuration Files​

There is one configuration file per home: config.yaml. It is plain YAML and is the single source for non-secret settings. A heavily commented example shipped with the source tree (configs/config.example.yaml) demonstrates every section.

A minimal, working file looks like this:

profile: default
timezone: ""              # IANA name (e.g. Asia/Shanghai); empty uses the host timezone

default_model: openai-compatible/your-model-name
main_model:
  provider_id: openai-compatible
  model: your-model-name

providers:
  - id: openai-compatible
    api_mode: openai-compatible
    base_url: https://api.openai.com/v1
    api_key_ref: env:OPENAI_API_KEY   # a reference, not the secret itself
    default_model: your-model-name

agent:
  max_turns: 90

The file is parsed strictly: unknown top-level or nested keys are rejected rather than ignored, so a typo in a key name produces a load error instead of being silently dropped.

Top-level sections you will encounter include providers, main_model, auxiliary_models, gateway, channels, toolsets, tool_governance, skills, memory, mcp, media_understanding, media_generation, tts, voice, storage, retention, and observability. Each is described in the configuration reference.

You normally do not edit config.yaml by hand. The setup wizard and subcommands such as anyy setup model, anyy setup channels, anyy mcp add, and anyy computer-use enable write the relevant sections for you.

Configuration Precedence​

Effective settings are resolved from lowest to highest priority:

  1. Built-in defaults. Every optional setting has a default applied at load time. Examples: profile defaults to default, agent.max_turns to 90, the gateway TCP listener to 0.0.0.0:8765 in open mode, and the gateway Unix socket to <home>/anyy.sock. A file that omits a key inherits its default.
  2. The configuration file. Any value present in config.yaml overrides the corresponding default.
  3. Command flags for location. --home selects which home (and therefore which config.yaml) is used; --config PATH points a command at a specific configuration file instead of <home>/config.yaml. These select which file is loaded; they do not override individual settings inside it.

There is no separate per-user or system-wide config file that merges with this one: a single config.yaml plus defaults defines the effective configuration for a home. To run multiple independent configurations, use separate homes (see Profiles).

warning

Because the current defaults enable the TCP gateway listener in open mode, set gateway.tcp.enabled: false if you only need local socket access, or explicitly bind and protect the TCP listener before using the gateway on a shared network.

Environment Variable Expansion​

Anyy does not perform general shell-style ${VAR} substitution inside config.yaml. Environment variables influence configuration in two specific ways:

  • Home selection. ANYY_HOME selects the home directory (and thus the config file) when --home is not given, as described above.

  • Secret references. Sensitive values are never written into config.yaml directly. Instead, fields ending in _ref (for example api_key_ref, token_ref, app_secret_ref) hold a typed reference that is resolved at runtime. The supported schemes are:

    SchemeResolves from
    env:NAMEthe NAME environment variable
    file:PATHthe contents of a file
    secret:scope/keyAnyy's managed secrets store under <home>/secrets
    literal:valuean inline literal value

    So api_key_ref: env:OPENAI_API_KEY reads the key from that environment variable at runtime; the key itself never appears in the file. See the environment variables reference for the full list of variables.

    Not every _ref field accepts every scheme. Provider and MCP credential-bearing fields reject literal: so secrets do not land in config.yaml.

Provider And Model Settings​

Provider connections and the active model are configured under providers, main_model / default_model, and auxiliary_models. These determine which service the assistant talks to and which model answers each turn. Because this is the most involved part of configuration, it has its own guide: Configuring Models. Reference fields live in the provider configuration reference.

Auxiliary Model Settings​

auxiliary_models defines model slots for non-primary work — fallback, image_understanding, video_understanding, speech_synthesis, search, and image_generation. Each slot lists one or more { provider_id, model } entries and may be individually enabled or disabled. These let a text-only main model delegate vision, speech, or search to a separate capable model. The related media_understanding block tunes how images, audio, and video are summarized into a turn. See Configuring Models for setup.

Tool Governance​

The tool_governance section adjusts how individual tools behave without changing code. Each override targets a tool by source and name and can set its risk, approval_policy, execution_policy, output budget, timeout, and whether it is enabled. This is how you raise or lower the approval requirement for a specific tool, or disable one entirely. Which toolsets are exposed to a turn is controlled separately by the toolsets section; see the toolsets reference.

Skills Settings​

The skills section controls skill catalog visibility and external roots:

skills:
  external_roots:
    - ~/.agents/skills
  disabled:
    - skill_user_abc123
  disabled_by_surface:
    tui:
      - noisy-helper

Use external_roots for shared read-only skill directories, and use disabled or disabled_by_surface to hide a skill ID, skill name, or command name. Installed and agent-created skills still live under <home>/skills. See Skills System and the configuration reference.

MCP Configuration​

MCP configuration has a client side, where Anyy connects to external MCP servers, and a server side, where Anyy can expose a bridge over stdio.

mcp:
  client:
    enabled: false
    servers: {}
  server:
    enabled: false
    transport: stdio

Use anyy mcp add, anyy mcp configure, anyy mcp test, and anyy mcp reload for normal management. MCP tools are only visible when the matching mcp-<server> toolset is selected. Field-level details are in the MCP config reference.

Memory Configuration​

The memory section controls long-term memory maintenance: maintenance_enabled toggles background upkeep, suggestion_ttl_days (default 14) sets how long memory suggestions live, and daily_keep_days (default 180) with daily_mode (default delete) govern how daily memory rollups are retained or pruned. Memory itself is stored under <home>/memory.

See Persistent Memory for the model-visible memory tool, trusted suggestion RPCs, background review, and exact maintenance behavior.

Context Configuration​

Conversation context assembly and compression are governed by the runtime. Compression keeps long sessions within the model's context window by summarizing older turns while protecting the most recent and earliest messages. The current effective defaults (visible via anyy config) are: enabled, compress at 50% of the window, target ~20%, protect the last 20 and first 3 messages. The retention section governs how much raw history and message preview text is kept on disk; see the configuration reference.

Channel Configuration​

Messaging platforms are configured under channels, keyed by platform — for example weixin, telegram, slack, discord, feishu, whatsapp, and others. Each channel block carries its own enabled flag, an account_id, a secret reference for its token (such as token_ref or bot_token_ref), and delivery policy fields like dm_policy and group_policy. The channel_webhooks section configures the optional webhook listener (disabled by default, 127.0.0.1:8770). Use anyy setup channels to configure these; field-level details are in the channels reference.

Dashboard Settings​

anyy config renders a read-only configuration summary for the active home: status, resolved paths, provider credential checks, the selected model, timezone, context compression defaults, and which messaging platforms are configured. It does not change anything — it is the quickest way to confirm what the running configuration resolves to. Live runtime health is reported separately by status and doctor.

Privacy And Redaction​

Secrets stay out of config.yaml by design: the file holds only _ref references, and the actual material lives in the environment, referenced files, or the managed secrets store under <home>/secrets. Diagnostic output redacts secret values — anyy config, for instance, reports a credential only as set / not set / invalid, never its contents. When sharing a config file or logs for support, the _ref model means you can share the file as-is without leaking keys.

Timezone​

The top-level timezone field sets the assistant's clock for scheduling, timestamps, and time-aware replies. It takes an IANA timezone name such as Asia/Shanghai or America/New_York. Leaving it empty ("") falls back to the gateway host's local timezone. The resolved timezone is shown by anyy config under Timezone ((host-local) when unset).