Configuration Reference

Complete reference for the nao_config.yaml file. This page is auto-generated from the Pydantic models in cli/nao_core/config/. Values wrapped in ${{ env('VAR') }} or {{ env('VAR') }} are resolved from environment variables at load time.

Resolving secrets

In addition to env(), any value in nao_config.yaml can pull a secret from AWS Secrets Manager or Kubernetes Secrets, so deployments can keep credentials out of plain environment variables:

Resolver	Syntax	Notes
`env`	`{{ env('VAR') }}`	Resolves from an environment variable. Missing values become an empty string.
`aws`	`{{ aws('secret_name/field') }}`	Reads from AWS Secrets Manager. The reference is split on its last `/`: everything before is the secret id, everything after is the field. Full ARNs are supported (`{{ aws('arn:aws:secretsmanager:eu-west-1:123:secret:foo-AbCdEf/key') }}`) and the region is auto-detected from the ARN.
`k8s`	`{{ k8s('namespace/secret/field') }}`	Reads from a Kubernetes Secret and base64-decodes the value. The namespace is optional (`{{ k8s('secret/field') }}`) and falls back to the pod namespace.

databases:
  - type: postgres
    name: prod-db
    user: ${{ env('DB_USER') }}
    password: '{{ aws("prod/db/credentials/password") }}'

slack:
  bot_token: '{{ k8s("default/slack-secrets/bot_token") }}'

AWS payloads and nested fields

An AWS secret payload must be a JSON object (binary secrets are not supported). The field part is a dot-path, so nested keys are addressed with .:

secret payload: {"port": 5432, "cred": {"user": "analytics"}}

{{ aws('prod/db/port') }}        -> "5432"
{{ aws('prod/db/cred.user') }}   -> "analytics"

The resolved value must be a scalar (string, number, or boolean); pointing at a nested object raises an error. Referencing the same secret several times in one config triggers a single backend call, the payload is cached for the duration of the load. The aws and k8s resolvers require optional dependencies: install nao-core[aws-secrets] or nao-core[k8s-secrets]. Unlike env, which resolves missing variables to an empty string and warns, aws and k8s raise a clear error at load time when a secret or field cannot be resolved.

Top-level properties

Property	Type	Required	Default	Description
`project_name`	string	Yes	—	The name of the nao project
`threads`	integer	No	`1`	Number of worker threads used by `nao sync`. Override per run with `nao sync -t/--threads`. Must be `1` or greater.
`databases`	DatabaseConfig[]	No	`[]`	The databases to use
`repos`	RepoConfig[]	No	`[]`	The repositories to use
`notion`	NotionConfig	No	`null`	The Notion configurations
`confluence`	ConfluenceConfig	No	`null`	The Confluence configuration
`llm`	LLMConfig	No	`null`	The LLM configuration
`slack`	SlackConfig	No	`null`	The Slack configuration
`mcp`	McpConfig	No	`null`	The MCP configuration
`skills`	SkillsConfig	No	`null`	The Skills configuration
`test`	TestConfig	No	`null`	The defaults used by `nao test`

Databases

All database configurations share these common fields:

Property	Type	Required	Default	Description
`type`	string — see below	Yes	—	—
`name`	string	Yes	—	A friendly name for this connection
`include`	string[]	No	`[]`	Glob patterns for schemas/tables to include (e.g., ‘prod_.’, ‘analytics.dim_*’). Empty means include all.
`exclude`	string[]	No	`[]`	Glob patterns for schemas/tables to exclude (e.g., ‘temp_.’, ‘.backup_‘)
`exclude_columns`	string[]	No	`[]`	Glob patterns matched against the fully-qualified `schema.table.column` name. Matching columns are dropped from everything the agent sees (column lists, previews, profiling). Useful for hiding replication metadata or internal columns (e.g., `'._peerdb_'`, `'*.version'`). Empty means no columns are hidden.
`templates`	string[]	No	`["columns", "query_history", "preview"]`	Which default templates to render per table (e.g., [‘columns’, ‘query_history’, ‘profiling’, ‘ai_summary’]). Defaults to [‘columns’, ‘query_history’, ‘preview’]. The legacy key `accessors` is still accepted.
`query_history_days`	integer	No	`0`	Number of days of query history to fetch for the `query_history` template. Set to 0 to disable.
`query_history_sql`	string	No	`null`	Custom SQL to override the built-in query history fetch. Must return a `query_text` column. Use `{days}` as a placeholder for `query_history_days`.
`query_history_exclude_patterns`	string[]	No	`[]`	Case-insensitive regex patterns. Queries matching any pattern are excluded from the `query_history` analysis.

Template values: columns, preview, query_history, profiling, ai_summary Patterns in include / exclude use glob syntax against schema.table (e.g. prod_*.*, analytics.dim_*).

PostgreSQL (`type: postgres`)

Property	Type	Required	Default	Description
`host`	string	Yes	—	PostgreSQL host
`port`	integer	No	`5432`	PostgreSQL port
`database`	string	Yes	—	Database name
`user`	string	Yes	—	Username
`password`	string	Yes	—	Password
`schema_name`	string	No	`null`	Default schema (optional, uses ‘public’ if not set)

Snowflake (`type: snowflake`)

Property	Type	Required	Default	Description
`username`	string	Yes	—	Snowflake username
`account_id`	string	Yes	—	Snowflake account identifier (e.g., ‘xy12345.us-east-1’)
`password`	string	No	`null`	Snowflake password
`database`	string	Yes	—	Snowflake database
`schema_name`	string	No	`null`	Snowflake schema (optional)
`warehouse`	string	No	`null`	Snowflake warehouse to use (optional)
`private_key_path`	string	No	`null`	Path to private key file for key-pair authentication
`passphrase`	string	No	`null`	Passphrase for the private key if it is encrypted
`authenticator`	`"externalbrowser"`, `"username_password_mfa"`, `"jwt_token"`, `"oauth"`	No	`null`	Authentication method (e.g., ‘externalbrowser’ for SSO)

BigQuery (`type: bigquery`)

Property	Type	Required	Default	Description
`project_id`	string	Yes	—	GCP project ID
`dataset_id`	string	No	`null`	Default BigQuery dataset
`credentials_path`	string	No	`null`	Path to service account JSON file. If not provided, uses Application Default Credentials (ADC)
`credentials_json`	object	No	`null`	Service account credentials as a dict or JSON string. Takes precedence over credentials_path if both are provided
`sso`	boolean	No	`false`	Use Single Sign-On (SSO) for authentication
`location`	string	No	`null`	BigQuery location

DuckDB (`type: duckdb`)

Property	Type	Required	Default	Description
`path`	string	No	`":memory:"`	Path to the DuckDB database file, or a MotherDuck connection string (e.g. `md:my_database`). See MotherDuck.

Connections to a local DuckDB file are locked down after connect: external access is disabled and the configuration is locked, so SQL cannot read local files, fetch remote URLs, or ATTACH another database. MotherDuck paths keep external access on, since the service itself is remote.

MotherDuck (`type: motherduck`)

Property	Type	Required	Default	Description
`database`	string	No	`null`	MotherDuck database name. Connects to the account’s default database when empty
`token`	string	No	`null`	MotherDuck access token. Falls back to the `MOTHERDUCK_TOKEN` environment variable when omitted

Databricks (`type: databricks`)

Property	Type	Required	Default	Description
`server_hostname`	string	Yes	—	Databricks server hostname (e.g., ‘adb-xxxx.azuredatabricks.net’)
`http_path`	string	Yes	—	HTTP path to the SQL warehouse or cluster
`access_token`	string	Yes	—	Databricks personal access token
`catalog`	string	No	`null`	Unity Catalog name (optional)
`schema_name`	string	No	`null`	Default schema (optional)
`temp_schema`	string	No	`null`	A schema you have write access to, used for temporary storage during queries. Set this when `schema_name` is read-only. When set, it is used as the connection schema in place of `schema_name`.

Microsoft SQL Server (`type: mssql`)

Property	Type	Required	Default	Description
`host`	string	Yes	—	MSSQL host
`port`	integer	No	`1433`	MSSQL port
`database`	string	Yes	—	Database name
`user`	string	Yes	—	Username
`password`	string	Yes	—	Password
`driver`	string	No	`"FreeTDS"`	ODBC driver (FreeTDS on Mac/Linux, ODBC Driver 18 for SQL Server on Windows)
`schema_name`	string	No	`null`	Default schema (optional, uses ‘dbo’ if not set)

Amazon Redshift (`type: redshift`)

Property	Type	Required	Default	Description
`host`	string	Yes	—	Redshift cluster endpoint
`port`	integer	No	`5439`	Redshift port
`database`	string	Yes	—	Database name
`user`	string	Yes	—	Username
`password`	string	Yes	—	Password
`schema_name`	string	No	`null`	Default schema (optional, uses ‘public’ if not set)
`sslmode`	string	No	`"require"`	SSL mode for the connection
`ssh_tunnel`	RedshiftSSHTunnelConfig	No	`null`	SSH tunnel configuration (optional)

StarRocks (`type: starrocks`)

Property	Type	Required	Default	Description
`host`	string	Yes	-	StarRocks FE host
`port`	integer	No	`9030`	StarRocks FE query port
`database`	string	Yes	-	Database name
`user`	string	Yes	-	Username
`password`	string	Yes	-	Password
`catalogs`	string[]	No	`[]`	List of catalogs to sync (multi-catalog support)

Trino (`type: trino`)

Property	Type	Required	Default	Description
`host`	string	Yes	—	Trino coordinator host
`port`	integer	No	`8080`	Trino coordinator port (use `8443` for HTTPS)
`catalog`	string	Yes	—	Catalog name
`user`	string	Yes	—	Username
`schema_name`	string	No	`null`	Default schema (optional)
`password`	string	No	`null`	Password (optional). Requires `http_scheme: https`.
`http_scheme`	`"http"`, `"https"`	No	`"http"`	Connection scheme. Set to `https` for TLS-only coordinators (Starburst, Stackable, OPA-authorized OSS Trino). Required for password auth.
`verify`	boolean or string	No	`true`	TLS certificate verification when `http_scheme: https`. `true` uses system CAs, `false` disables verification, or pass a path to a CA bundle for an internal CA. Ignored on `http`.
`jwt_token`	string	No	`null`	Bearer JWT for Trino’s OAuth2/JWT authenticator. Takes precedence over `password` and forces `http_scheme: https`.
`jwt_token_file`	string	No	`null`	Path to a file holding the bearer JWT. Read on every connection, so an external refresher can rotate short-lived tokens without rewriting the config. Takes precedence over `jwt_token`.

ClickHouse (`type: clickhouse`)

Property	Type	Required	Default	Description
`host`	string	Yes	-	ClickHouse server host
`protocol`	`"http"`, `"native"`	No	`"http"`	Wire protocol. `http` uses the HTTP interface, `native` uses the TCP protocol for instances that do not expose HTTP.
`port`	integer	No	`null`	Server port. Defaults to 8123 (HTTP) / 8443 (HTTPS) for `protocol: http`, and 9000 (TCP) / 9440 (TCP+TLS) for `protocol: native`.
`database`	string	Yes	-	Database name
`user`	string	Yes	-	Username
`password`	string	No	`""`	Password
`secure`	boolean	No	`false`	Use HTTPS for `protocol: http`, or TLS over TCP for `protocol: native`.
`verify`	boolean	No	`true`	Verify TLS certificates when using `protocol: native` with `secure: true`.
`connect_timeout`	integer	No	`null`	Connection timeout in seconds, passed to the underlying ClickHouse client.
`send_receive_timeout`	integer	No	`null`	Send/receive timeout in seconds, passed to the underlying ClickHouse client.

Unlike other database types, ClickHouse renders all available templates by default rather than the shared default set. System databases (system, information_schema, INFORMATION_SCHEMA) are skipped unless explicitly listed in include.

Amazon Athena (`type: athena`)

Property	Type	Required	Default	Description
`s3_staging_dir`	string	Yes	—	S3 staging directory for query results
`region_name`	string	Yes	—	AWS region name
`aws_access_key_id`	string	No	`null`	AWS access key ID
`aws_secret_access_key`	string	No	`null`	AWS secret access key
`aws_session_token`	string	No	`null`	AWS session token
`profile_name`	string	No	`null`	AWS profile name
`schema_name`	string	No	`null`	Athena schema name
`work_group`	string	No	`"primary"`	Athena workgroup

RedshiftSSHTunnelConfig

Nested under ssh_tunnel in a Redshift database entry.

Property	Type	Required	Default	Description
`ssh_host`	string	Yes	—	SSH host
`ssh_port`	integer	No	`22`	SSH port
`ssh_username`	string	Yes	—	SSH username
`ssh_private_key_path`	string	Yes	—	Path to SSH private key file
`ssh_private_key_passphrase`	string	No	`null`	SSH private key passphrase (optional)

LLM

Property	Type	Required	Default	Description
`providers`	ProviderConfig[]	No	`[]`	The LLM providers to use
`annotation_model`	string	No	`null`	Model to use for ai_summary generation via prompt(…) in Jinja templates
`meta`	object	No	`null`	Deprecated: declare costs on the matching model instead

Declaring the provider inline (llm.provider, llm.api_key, …) still works but is deprecated. Run nao migrate to rewrite an existing file into the llm.providers shape.

ProviderConfig

One entry per provider under llm.providers.

Property	Type	Required	Default	Description
`provider`	`"openai"`, `"anthropic"`, `"mistral"`, `"gemini"`, `"openrouter"`, `"ollama"`, `"bedrock"`, `"vertex"`	Yes	—	The LLM provider to use
`api_key`	string	No	`null`	The API key to use
`base_url`	string	No	`null`	Optional custom base URL for the provider API
`access_key`	string	No	`null`	AWS access key (only for Bedrock)
`secret_key`	string	No	`null`	AWS secret key (only for Bedrock)
`aws_region`	string	No	`null`	AWS region (only for Bedrock)
`aws_profile`	string	No	`null`	AWS CLI profile name (only for Bedrock, e.g. SSO profile)
`gcp_project`	string	No	`null`	GCP project ID (only for Vertex)
`gcp_location`	string	No	`null`	GCP location (only for Vertex)
`service_account_json`	string	No	`null`	Service account JSON (only for Vertex)
`key_file`	string	No	`null`	Path to service account key file (only for Vertex)
`models`	ModelConfig[]	No	`[]`	The models to expose for this provider, in display order
`budget`	BudgetConfig	No	`null`	Spend limit for this provider, enforced by the chat app

BudgetConfig

A spend limit for one provider under llm.providers[].budget, enforced by the chat app and shown on its Budgets page. At least one of limit and per_user_limit is required.

Property	Type	Required	Default	Description
`limit`	number	No	`null`	Project-wide spend limit in US dollars for the period
`per_user_limit`	number	No	`null`	Spend limit in US dollars per user for the period
`period`	`"day"`, `"week"`, `"month"`	No	`"month"`	How often the limit resets

ModelConfig

One entry per model under llm.providers[].models. Leave models empty to expose the provider’s built-in models.

Property	Type	Required	Default	Description
`id`	string	Yes	—	The model identifier used by the provider
`name`	string	No	`null`	Display name shown in the model picker
`default`	boolean	No	`false`	Preselect this model for new chats
`costs`	ModelCosts	No	`null`	Price in US dollars per million tokens
`settings`	object	No	`null`	Inference parameters for this model, e.g. temperature or reasoning_effort

ModelCosts

Nested under costs in a model entry. Prices are in US dollars per million tokens.

Property	Type	Required	Default	Description
`input_no_cache`	number	No	`null`	Price of an uncached input token
`input_cache_read`	number	No	`null`	Price of an input token read from cache
`input_cache_write`	number	No	`null`	Price of an input token written to cache
`output`	number	No	`null`	Price of an output token

Provider authentication

Provider	Env variable	API key	Base URL env
`openai`	`OPENAI_API_KEY`	required	`OPENAI_BASE_URL`
`anthropic`	`ANTHROPIC_API_KEY`	required	`ANTHROPIC_BASE_URL`
`mistral`	`MISTRAL_API_KEY`	required	`MISTRAL_BASE_URL`
`gemini`	`GEMINI_API_KEY`	required	`GEMINI_BASE_URL`
`openrouter`	`OPENROUTER_API_KEY`	required	`OPENROUTER_BASE_URL`
`ollama`	`OLLAMA_API_KEY`	none	`OLLAMA_BASE_URL`
`bedrock`	`AWS_BEARER_TOKEN_BEDROCK`	optional	—
`vertex`	`VERTEX_GOOGLE_SERVICE_ACCOUNT_JSON`	none	—

Default annotation models

Used for ai_summary generation when annotation_model is not set.

Provider	Default model
`openai`	`gpt-4.1-mini`
`anthropic`	`claude-3-5-sonnet-latest`
`mistral`	`mistral-small-latest`
`gemini`	`gemini-2.0-flash`
`openrouter`	`openai/gpt-4.1-mini`
`ollama`	`llama3.2`
`bedrock`	`anthropic.claude-3-5-sonnet-20241022-v2:0`
`vertex`	`gemini-2.5-flash`

Repos

Property	Type	Required	Default	Description
`name`	string	Yes	-	The name of the repository
`url`	string	No	`null`	The URL of the Git repository to clone
`branch`	string	No	`null`	The branch to check out. Only valid with `url`.
`local_path`	string	No	`null`	Local filesystem path, relative to `nao_config.yaml` or absolute
`include`	string[]	No	`[]`	Glob patterns for files to include (e.g. `'models/*/.sql'`). Empty means include all.
`exclude`	string[]	No	`[]`	Glob patterns for files to exclude (e.g. `'*.pyc'`)

Set exactly one of url or local_path: supplying both, or neither, fails validation. branch cannot be combined with local_path. include and exclude are applied to both source types. For a url repository the full repo is cloned first, then non-matching files are dropped, so the globs control what ends up in your context rather than what is fetched.

Notion

Property	Type	Required	Default	Description
`api_key`	string	Yes	—	The API key to use
`pages`	string[]	Yes	—	The pages to sync

Confluence

Property	Type	Required	Default	Description
`base_url`	string	Yes	—	The Confluence base URL, e.g. `https://acme.atlassian.net/wiki` (Cloud) or `https://confluence.acme.com` (Data Center/Server)
`deployment`	`"cloud"`, `"server"`	No	`"cloud"`	Which Confluence flavour to talk to: `cloud` or `server` (Data Center/Server)
`email`	string	No	`null`	Account email for Confluence Cloud (Basic auth username)
`api_token`	string	No	`null`	API token for Confluence Cloud (Basic auth password)
`personal_access_token`	string	No	`null`	Personal access token for Confluence Data Center/Server (Bearer auth)
`username`	string	No	`null`	Username for Data Center/Server Basic auth
`password`	string	No	`null`	Password for Data Center/Server Basic auth
`pages`	string[]	No	`[]`	The pages to sync, as numeric page IDs or URLs that carry one
`page_trees`	string[]	No	`[]`	Pages whose whole subtree to sync (the page and all its descendants), as IDs or URLs
`labels`	string[]	No	`[]`	Labels to sync; every page carrying one is pulled. Scope to a space with `SPACE:label`
`spaces`	string[]	No	`[]`	The space keys to sync in full, e.g. `ENG` or `DATA`

Cloud requires both email and api_token. Data Center/Server requires either personal_access_token or both username and password. At least one of pages, page_trees, labels, or spaces must be set. See the Confluence context provider guide for what gets synced and where it lands.

Slack

Property	Type	Required	Default	Description
`bot_token`	string	Yes	—	The bot token to use
`signing_secret`	string	Yes	—	The signing secret for verifying requests
`post_message_url`	string	No	`"https://slack.com/api/chat.postMessage"`	The Slack API URL for posting messages

MCP

Property	Type	Required	Default	Description
`json_file_path`	string	Yes	—	Path to the MCP JSON configuration file

Skills

Property	Type	Required	Default	Description
`folder_path`	string	Yes	—	Path to the skills folder

Test

Defaults for nao test. Every property is overridden by the matching command line flag.

Property	Type	Required	Default	Description
`models`	string[]	No	`["openai:gpt-4.1"]`	The models to run the tests against, in the format ‘provider:model_id’
`threads`	integer	No	`1`	Number of test runs to execute in parallel
`comparison`	ComparisonConfig	No	—	Tolerances used when comparing results to the expected data

ComparisonConfig

Nested under test.comparison. Controls how results are compared to the expected data.

Property	Type	Required	Default	Description
`rtol`	number	No	`1e-05`	Relative tolerance used to compare numeric values
`atol`	number	No	`1e-08`	Absolute tolerance used to compare numeric values
`decimals`	integer	No	`2`	Decimals kept when rounding float values before comparing

Example

project_name: my-project

databases:
  - type: postgres
    name: prod-db
    host: localhost
    port: 5432
    database: analytics
    user: ${{ env('DB_USER') }}
    password: ${{ env('DB_PASSWORD') }}
    include:
      - "public.*"
    exclude:
      - "public.tmp_*"
    exclude_columns:
      - "*._peerdb_*"
    templates:
      - columns
      - query_history
      - preview
      - ai_summary

  - type: duckdb
    name: local
    path: ./warehouse.duckdb

repos:
  - name: dbt-models
    url: https://github.com/myorg/dbt-models.git
    branch: main

llm:
  annotation_model: gpt-4.1-mini
  providers:
    - provider: openai
      api_key: ${{ env('OPENAI_API_KEY') }}
      models:
        - id: gpt-4.1
          default: true
        - id: gpt-4.1-mini
          name: GPT-4.1 mini
          costs: # US dollars per million tokens
            input_no_cache: 0.4
            input_cache_read: 0.1
            output: 1.6
    - provider: anthropic
      api_key: ${{ env('ANTHROPIC_API_KEY') }}
      models:
        - id: claude-sonnet-4-5
          settings:
            temperature: 0

notion:
  api_key: ${{ env('NOTION_API_KEY') }}
  pages:
    - https://notion.so/my-page-id

slack:
  bot_token: ${{ env('SLACK_BOT_TOKEN') }}
  signing_secret: ${{ env('SLACK_SIGNING_SECRET') }}

mcp:
  json_file_path: ./agent/mcps/mcp.json

skills:
  folder_path: ./agent/skills/

test:
  models:
    - openai:gpt-4.1
    - anthropic:claude-sonnet-4-5
  threads: 4
  comparison:
    rtol: 0.00001
    atol: 0.00000001
    decimals: 2

JSON Schema

The raw JSON Schema is available at config-schema.json.

​Configuration Reference

​Resolving secrets

​AWS payloads and nested fields

​Top-level properties

​Databases

​PostgreSQL (type: postgres)

​Snowflake (type: snowflake)

​BigQuery (type: bigquery)

​DuckDB (type: duckdb)

​MotherDuck (type: motherduck)

​Databricks (type: databricks)

​Microsoft SQL Server (type: mssql)

​Amazon Redshift (type: redshift)

​StarRocks (type: starrocks)

​Trino (type: trino)

​ClickHouse (type: clickhouse)

​Amazon Athena (type: athena)

​RedshiftSSHTunnelConfig

​LLM

​ProviderConfig

​BudgetConfig

​ModelConfig

​ModelCosts

​Provider authentication

​Default annotation models

​Repos

​Notion

​Confluence

​Slack

​MCP

​Skills

​Test

​ComparisonConfig

​Example

​JSON Schema