> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnao.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Initialize and configure your nao project

# nao init

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

**Run nao init**

```bash theme={null}
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.

The command will guide you through an interactive setup:

**1. Project Name**

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

**2. Database Connection (Optional)**

```
Do you want to connect a database? [y/N]
> y

Select your database type:
  1. Snowflake
  2. BigQuery
  3. Databricks
  4. PostgreSQL
  5. Redshift
  6. MySQL
```

If you select yes, you'll be prompted for connection details specific to your database type.

You will also be asked whether to enable the **profiling** template on the databases you just configured:

```
Enable profiling template for all configured databases? (can be costly on large datasets) (y/N)
```

The prompt defaults to **no**. Profiling scans your tables to compute per-column statistics (null counts, distinct values, top values) during `nao sync`, which can be expensive on large warehouses. Leave it off to start and enable it per database later in `nao_config.yaml` once you know you want the extra context. Configs that already list `profiling` under `templates` keep working as-is - the prompt only applies to newly configured databases.

**3. Repository Context (Optional)**

```
Do you want to add a repository to your agent context? [y/N]
> y

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

Path within repo (optional):
> models/
```

**4. LLM API Key (Optional)**

```
Do you want to add an LLM key? [y/N]
> y

Select your LLM provider:
  1. OpenAI
  2. Anthropic
  3. Mistral
  4. Gemini
  5. OpenRouter
  6. Ollama
  7. AWS Bedrock
```

If you use Ollama provider, you can skip adding an LLM key as Ollama does not require it.

**5. Slack Integration (Optional)**

```
Do you want to setup a Slack connection? [y/N]
> y
```

<Info>
  You can skip any optional step and configure it later by editing `nao_config.yaml`.
</Info>

**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:

```bash theme={null}
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:

```bash theme={null}
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**

```yaml theme={null}
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:
  provider: anthropic
  api_key: {{ env('ANTHROPIC_API_KEY') }}
  # Optional model used by database ai_summary templates (when ai_summary template is enabled)
  annotation_model: claude-3-7-sonnet-latest
  # Optional: route through an OpenAI-compatible proxy such as LiteLLM
  # base_url: http://0.0.0.0:4000
  # Optional for Bedrock provider
  aws_region: us-east-1

# Local Ollama example (no API key required)
llm:
  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
```

**Environment Variables**

<Warning>
  **Never commit sensitive credentials to Git!** Always use environment variables for secrets.
</Warning>

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

```bash theme={null}
# .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:

```yaml theme={null}
api_key: {{ env('OPENAI_API_KEY') }}
user: {{ env('SNOWFLAKE_USER') }}
password: {{ env('SNOWFLAKE_PASSWORD') }}
```

AWS Bedrock with bearer token:

```yaml theme={null}
llm:
  provider: bedrock
  api_key: {{ env('AWS_BEARER_TOKEN_BEDROCK') }}
```

AWS Bedrock with IAM credentials:

```yaml theme={null}
llm:
  provider: bedrock
  access_key: {{ env('AWS_ACCESS_KEY_ID') }}
  secret_key: {{ env('AWS_SECRET_ACCESS_KEY') }}
  aws_region: {{ env('AWS_REGION') }}
```

**OpenAI-compatible proxy (LiteLLM)**

To route the agent through an LLM proxy such as [LiteLLM](https://docs.litellm.ai/), keep the underlying provider and add `base_url` pointing at the proxy endpoint:

```yaml theme={null}
llm:
  provider: openai
  api_key: {{ env('LITELLM_API_KEY') }}
  base_url: http://0.0.0.0:4000
  # Model used by database ai_summary templates, prefixed with the provider
  annotation_model: openai/gpt-5.2
```

`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.

<Info>
  When running nao chat, you can also set a custom endpoint per provider from the admin UI under **Settings** -> **Project** -> **Models** -> **Advanced settings** -> **Custom Base URL**. UI values override `nao_config.yaml` but reset to it on restart, so configure `base_url` here for a durable setup. See [Choose LLM models](/nao-agent/chat/admin/setup#choose-llm-models).
</Info>

**Warehouse Credentials**

For Warehouse credentials, you can use either method:

**Method 1: credentials\_path (local development)**

```yaml theme={null}
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)**

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

<Info>
  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.
</Info>

<Warning>
  When using `credentials_json`, the environment variable must contain the **entire JSON content** of your service account key file, not just the path.
</Warning>

**Next Steps**

<CardGroup cols={2}>
  <Card title="Context Synchronization" icon="sync" href="/nao-agent/context-builder/synchronization">
    Learn how to sync and update your agent's context
  </Card>

  <Card title="Context Principles" icon="lightbulb" href="/nao-agent/context-engineering/principles">
    Learn how to optimize your context for reliability, speed, and cost
  </Card>
</CardGroup>