nao init

The nao init command sets up your context repository with all necessary files and structure. Run nao init

nao init

If nao_config.yaml already exists, nao init runs an update flow and lets you adjust existing configuration values instead of starting from scratch. nao init keeps the interactive setup to the essentials - project name, one database, one LLM, and one git repository. Everything else (extra databases and repos, Slack, Notion, MCP servers, skills, profiling) is configured afterwards by editing nao_config.yaml. 1. Project Name

What is the name of your project?
> my-analytics-agent

The project name defaults to the current folder name - press Enter to accept it, or type a different name. 2. Database Connection (Optional)

Set up database connections? [Y/n]
> y

Select database type:
  1. Snowflake
  2. BigQuery
  3. Databricks
  4. PostgreSQL
  ...

If you say yes, you’ll be prompted for the connection details specific to your database type. The database is scaffolded with the columns and preview templates (plus ai_summary when you configure an LLM); profiling and query_history are written as commented-out options you can enable later. See Databases for the full template and connection reference. 3. LLM API Key (Optional)

Select your LLM provider:
OpenAI
Anthropic
Mistral
Gemini
OpenRouter
Ollama
AWS Bedrock
Google Vertex AI

If you use the Ollama provider you can skip the API key, as Ollama does not require one. To offer several providers or models, add them to the llm.providers list in nao_config.yaml afterwards - see LLM providers and models. 4. Git Repository (Optional)

Set up git repositories? [Y/n]
> y

Repository URL:
> https://github.com/your-org/dbt-project

Path within repo (optional):
> models/

nao init sets up a single database, LLM, and repo. To add more, or to configure Slack, Notion, MCP servers, or skills, edit nao_config.yaml directly - re-running nao init on an existing project opens an update flow instead of starting over.

What Gets Created After running nao init, you’ll have a folder with the architecture of your context:

my-analytics-agent/
├── nao_config.yaml          # Main configuration file
├── RULES.md                 # Agent behavior rules
├── agent/                   # Agent tools and integrations
│   ├── mcps/               # Model Context Protocols (MCP servers)
│   ├── skills/             # Reusable skills workflows
│   └── tools/              # Custom tools
├── databases/              # Database schemas (populated after sync)
└── docs/                   # Documentation files (including synced Notion pages)

MCP servers are configured via the agent/mcps/mcp.json file, while skills are defined as markdown files in the agent/skills/ folder. Both are part of your project context and are discovered automatically by the agent.

nao sync

Once initialized, populate your context with actual content:

nao sync

This will:

Connect to configured databases and pull schemas
Clone configured repositories
Sync configured Notion pages into markdown files under docs/notion/
Generate structured context files
Index content for your agent

nao debug

Verify your configuration:

nao debug

This checks:

Configuration file syntax
Database connectivity
LLM API access
Environment variables
File permissions

nao_config.yaml

The nao_config.yaml file is the central configuration for your analytics agent. You can always edit it and re-launch a sync with this configuration. Basic Structure

project_name: my-analytics-agent

# Database Connections
databases:
  - name: bigquery-prod
    type: bigquery
    project_id: my-project
    dataset_id: analytics
    # Option 1: Use credentials_path for local files
    credentials_path: /path/to/credentials.json
    # Option 2: Use credentials_json for environment variables (recommended for cloud deployments)
    # credentials_json: {{ env('GCP_SERVICE_ACCOUNT_KEY_JSON') }}
    templates:
      - columns
      - preview
      - query_history
      # Optional (requires llm config below):
      # - ai_summary
      - profiling
    profiling:
      refresh_policy: always     # always (default), interval, or once
      interval_days: 7           # used only when refresh_policy: interval
    # ai_summary takes the same refresh config (requires llm config below):
    # ai_summary:
    #   refresh_policy: always
    #   interval_days: 7
    include: []
    exclude: []
    sso: false
    location: US

# Repository Integrations
repos:
  - name: dbt
    url: https://github.com/your-org/dbt-project.git
    branch: main

# LLM Configuration
llm:
  # Optional model used by database ai_summary templates (when ai_summary template is enabled)
  annotation_model: claude-3-7-sonnet-latest
  providers:
    - provider: anthropic
      api_key: {{ env('ANTHROPIC_API_KEY') }}
      # Optional: restrict the models offered in the chat model picker
      models:
        - id: claude-sonnet-4-5
          default: true
        - id: claude-3-7-sonnet-latest
    # Local Ollama example (no API key required)
    - provider: ollama

# Slack Integration (optional)
slack:
  bot_token: {{ env('SLACK_BOT_TOKEN') }}
  signing_secret: {{ env('SLACK_SIGNING_SECRET') }}
  post_message_url: https://slack.com/api/chat.postMessage

# Notion Integration (optional)
notion:
  api_key: {{ env('NOTION_API_KEY') }}
  pages:
    - 0123456789abcdef0123456789abcdef
    - fedcba9876543210fedcba9876543210

# Defaults for nao test (optional)
test:
  models:
    - anthropic:claude-sonnet-4-5
  threads: 4

Every key is documented in the configuration reference. The llm block is detailed in LLM providers and models below, and the test block in Evaluation. Environment Variables

Never commit sensitive credentials to Git! Always use environment variables for secrets.

Store sensitive values in environment variables (examples for different providers and warehouses):

# .env file (add to .gitignore)

# OpenAI / Anthropic / Azure OpenAI
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=...

# AWS Bedrock (choose one auth method)
# Option 1: bearer token
AWS_BEARER_TOKEN_BEDROCK=...

# Option 2: IAM credentials
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

# Warehouse credentials
SNOWFLAKE_USER=my_user
SNOWFLAKE_PASSWORD=my_password

# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
AWS_REGION=us-east-1

Reference them in your config:

api_key: {{ env('OPENAI_API_KEY') }}
user: {{ env('SNOWFLAKE_USER') }}
password: {{ env('SNOWFLAKE_PASSWORD') }}

Warehouse Credentials For Warehouse credentials, you can use either method: Method 1: credentials_path (local development)

databases:
  - name: bigquery-prod
    type: bigquery
    project_id: my-project
    dataset_id: analytics
    credentials_path: /path/to/service-account.json

Method 2: credentials_json (cloud deployments)

databases:
  - name: bigquery-prod
    type: bigquery
    project_id: my-project
    dataset_id: analytics
    credentials_json: {{ env('GCP_SERVICE_ACCOUNT_KEY_JSON') }}

Use credentials_json for cloud deployments (Cloud Run, GitHub Actions, etc.) where you store the full JSON content in an environment variable or secret manager. Use credentials_path for local development with credential files.

When using credentials_json, the environment variable must contain the entire JSON content of your service account key file, not just the path.

LLM providers and models

The llm block holds a list of providers under providers, and each provider lists the models it exposes. Use it to offer your users a choice of models, to expose models nao doesn’t know about (a proxy alias, a fine-tune, a model released after your nao version), and to price each of them.

llm:
  # Model used by database ai_summary templates and background tasks
  annotation_model: gpt-4.1-mini
  providers:
    - provider: openai
      api_key: {{ env('OPENAI_API_KEY') }}
      models:
        - id: gpt-4.1
          default: true         # preselected for new chats
        - id: gpt-4.1-mini
          name: GPT-4.1 mini    # label shown in the model picker
          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      # inference parameters for this model

A provider can appear only once, and only one model per provider can be the default. Leave models out to expose the provider’s built-in model list, which is what nao init writes. Every provider you declare is picked up by nao chat, nao debug and nao test. The chat server reads the block directly, so models, display names, inference settings and prices reach the app without any extra environment variable.

Providers declared in nao_config.yaml show up in the admin UI under Settings -> Project -> Models, badged nao_config.yaml. Editing one there saves an override in the database that keeps winning over the file until you delete it, so the file remains the durable source of truth. Resolution order per provider is admin UI -> nao_config.yaml -> environment variables. See Choose LLM models.

Provider credentials

AWS Bedrock with a bearer token:

llm:
  providers:
    - provider: bedrock
      api_key: {{ env('AWS_BEARER_TOKEN_BEDROCK') }}
      aws_region: us-east-1

AWS Bedrock with IAM credentials:

llm:
  providers:
    - provider: bedrock
      access_key: {{ env('AWS_ACCESS_KEY_ID') }}
      secret_key: {{ env('AWS_SECRET_ACCESS_KEY') }}
      aws_region: {{ env('AWS_REGION') }}

Bedrock also accepts aws_profile to use a named AWS CLI profile, such as an SSO one, instead of inline keys. Google Vertex AI, authenticating with Application Default Credentials, an inline service account or a key file:

llm:
  providers:
    - provider: vertex
      gcp_project: my-gcp-project
      gcp_location: us-east5
      # service_account_json: {{ env('GCP_SERVICE_ACCOUNT_KEY_JSON') }}
      # key_file: /path/to/service-account.json

OpenAI-compatible proxy (LiteLLM)

To route the agent through an LLM proxy such as LiteLLM, keep the underlying provider and add base_url pointing at the proxy endpoint:

llm:
  # Model used by database ai_summary templates, prefixed with the provider
  annotation_model: openai/gpt-5.2
  providers:
    - provider: openai
      api_key: {{ env('LITELLM_API_KEY') }}
      base_url: http://0.0.0.0:4000
      models:
        - id: gpt-5.2
        - id: claude-sonnet-4-5

base_url is supported on the openai, anthropic, and openrouter providers. nao debug runs its connectivity check against this base URL, so the test reflects the endpoint your agent actually calls. Because a proxy exposes model IDs nao has no price for, list them under models with their costs to keep cost tracking accurate.

Model costs

nao ships a price table for the models it knows and computes the cost of every call from it. A costs block on a model overrides that table token type by token type:

llm:
  providers:
    - provider: openai
      api_key: {{ env('LITELLM_API_KEY') }}
      base_url: http://0.0.0.0:4000
      models:
        - id: my-proxy-alias
          name: Internal GPT
          costs:
            input_no_cache: 2.5
            input_cache_read: 0.25
            input_cache_write: 3.13
            output: 10

All four fields are optional and expressed in US dollars per million tokens; the ones you leave out fall back to nao’s table. These prices feed the usage dashboard, the budgets, and the cost column of nao test.

Migrating an older config

Before multiple providers were supported, the llm block declared a single provider inline:

llm:
  provider: anthropic
  api_key: {{ env('ANTHROPIC_API_KEY') }}
  annotation_model: claude-3-7-sonnet-latest

That shape still loads — nao reads it as a one-entry providers list — but it prints a deprecation warning and cannot express several providers or per-model costs. Rewrite it with:

nao migrate

# Print the result without touching the file
nao migrate --dry-run

The command only touches the llm block and rewrites it as text, so comments and {{ env('...') }} references survive untouched.

llm.meta.costs is deprecated. Prices declared there apply to every model, which gets misleading as soon as you run more than one. Move them to the costs of the matching model.

Next Steps

Context Synchronization

Learn how to sync and update your agent’s context

Context Principles

Learn how to optimize your context for reliability, speed, and cost

Get Started

Context Builder

Context Engineering

Chat Interface

Connectors

Self-Hosting

nao Cloud

nao Enterprise

Developers

Configuration

nao init

nao sync

nao debug

nao_config.yaml

LLM providers and models

Provider credentials

OpenAI-compatible proxy (LiteLLM)

Model costs

Migrating an older config

Context Synchronization

Context Principles

​nao init

​nao sync

​nao debug

​nao_config.yaml

​LLM providers and models

​Provider credentials

​OpenAI-compatible proxy (LiteLLM)

​Model costs

​Migrating an older config

Context Synchronization

Context Principles

nao init

nao sync

nao debug

nao_config.yaml

LLM providers and models

Provider credentials

OpenAI-compatible proxy (LiteLLM)

Model costs

Migrating an older config