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

# Setup

> Configure users, authentication, models, and prompts for nao chat

As an admin, you can configure how your team accesses nao chat, manage integrations, choose models, and customize agent behavior.

# Access the admin panel

The admin views are exposed from the same server as the chat UI.

1. Start nao chat locally (see the [chat overview](/nao-agent/chat/overview) for details).
2. Sign in with an admin-capable account.
3. Navigate to the admin section from the UI navigation.

The admin panel includes sections for:

* **Project** - General project settings and Google OAuth
* **Models** - LLM provider configuration
* **Agent** - Agent settings and template prompts
* **MCP Servers** - Model Context Protocol server configuration
* **File Explorer** - Read-only browsing of your context folder files
* **Slack** - Slack bot integration
* **Telegram** - Telegram bot integration and user linking
* **WhatsApp** - WhatsApp bot integration and user linking
* **Team** - User management
* **Usage & Costs** - Usage analytics, feedbacks, and chats replay (Chats Replay is also available to the Context Admin role)
* **Recommendations** - Suggested context improvements mined from usage (available to Admin and Context Admin roles)

# Add Users

<Info>
  User management is available for deployed instances. If you're running nao locally with `nao chat`, user management is not required. For deployment instructions, see the [Deployment Guide](/nao-agent/self-hosting/deployment-guide).
</Info>

**To add a new user to a project:**

1. Navigate to **Team** in the left sidebar.
2. Click the **+** button in the top right of the Users panel.
3. Enter the user's email address
4. Pick a **role** (see below).
5. The user will then have to sign in with its email address and the generated password.

If you want to let users sign up autonomously, you can setup Google OAuth - see in next section.

<Info>
  The first user to sign up after deployment automatically becomes an admin. Additional users must be added through the admin interface. For more details on deploying nao, see the [Deployment Guide](/nao-agent/self-hosting/deployment-guide#step-5-customize-your-setup).
</Info>

## User roles

Each user belongs to one project role:

* **Admin** - full access. Can manage users, integrations, models, prompts, budgets, and read every chat and story in the project.
* **Context Admin** - uses nao like a Member, plus read access to two observability surfaces that are otherwise admin-only: **Recommendations** and **Chats Replay**. Does not get other admin capabilities (LLM config, team management, usage & costs, logs, or project settings). Use this role for context owners who need to see how the agent performs on real usage without giving them full admin.
* **Member** - default role for new users. Can chat with the agent, create and share stories, edit memories scoped to their own conversations.
* **Viewer** - read-only. Can open shared stories and shared chats sent to them, but cannot start a new chat, edit context, or change settings. Use this role for stakeholders who only consume insights.

Change a user's role from **Team** -> click the user -> **Role**.

### Default role for new users

By default, new users created through any onboarding path (admin invite to org or project, or messaging-provider auto-creation from Slack/Telegram/WhatsApp) get the **Member** role. Set the `DEFAULT_USER_ROLE` environment variable to change this:

```bash theme={null}
DEFAULT_USER_ROLE=viewer   # admin | user | viewer (defaults to "user" when unset)
```

Set `DEFAULT_USER_ROLE=viewer` for deployments where most people should consume insights read-only and only a few admins build context. Leaving it unset keeps the existing **Member** default.

# Reset user passwords with SMTP

If SMTP is configured, nao exposes a password reset flow for email and password users.

What users get:

* A **Forgot password** link on the login page
* A reset email with a secure link
* A dedicated **Reset password** page to choose a new password

What admins need:

1. Configure SMTP for the deployment
2. Make sure your public app URL is correct so reset links point back to your nao instance
3. Test the flow from the login page with a real user account

If SMTP is not configured, the forgot-password and reset-password routes stay unavailable.

**Reset a password from the CLI**

When SMTP is not configured, or a user is locked out, an admin with access to the deployment can reset a password directly against the local database with the `reset-password` command:

```bash theme={null}
nao reset-password user@example.com
```

The command generates a temporary password, stores it hashed, and prints it once so you can hand it to the user to sign in and change. This works without a running mail server or browser flow.

# Configure Google OAuth

<Info>
  Google OAuth configuration is for deployed instances. This allows users to sign in with their Google accounts instead of manually created accounts. For deployment instructions, see the [Deployment Guide](/nao-agent/self-hosting/deployment-guide#step-5-customize-your-setup).
</Info>

Enable Google sign-in for your team and control which domains can self-register.

**Step 1: Create Google OAuth Credentials**

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Navigate to **APIs & Services** → **Credentials**
4. Click **Create Credentials** → **OAuth client ID**
5. Configure the OAuth consent screen if prompted
6. Select **Web application** as the application type
7. Add authorized redirect URIs:
   ```
   https://your-deployed-instance-url/api/auth/callback/google
   ```
8. Copy the **Client ID** and **Client Secret**

**Step 2: Configure in nao Admin Panel**

1. Navigate to **Project** in the admin sidebar
2. Scroll to the **Google Credentials** section
3. Under **Google OAuth (Override Env)**, enter your **Client ID**
4. Click the **ENV** button to manage environment variables if needed
5. Set the following environment variables in your deployment:
   ```bash theme={null}
   GOOGLE_CLIENT_ID=your-client-id-here
   GOOGLE_CLIENT_SECRET=your-client-secret-here
   ```

**Step 3: Configure Allowed Domains**

To restrict sign-up to specific email domains:

1. Set the `GOOGLE_ALLOWED_DOMAINS` environment variable:
   ```bash theme={null}
   GOOGLE_ALLOWED_DOMAINS=getnao.io,example.com
   ```
2. Only users with email addresses from these domains will be able to sign up

<Warning>
  If you configure Google OAuth, users can sign in with their Google accounts. Make sure to set allowed domains if you want to restrict access to your organization.
</Warning>

## Configure GitHub SSO

Enable GitHub sign-in so your team can log in with their GitHub accounts.

1. Create a GitHub OAuth App at [github.com/settings/developers](https://github.com/settings/developers).
2. Set the following environment variables:

```bash theme={null}
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_SSO=true
```

3. Optionally restrict access to specific GitHub usernames:

```bash theme={null}
GITHUB_ALLOWED_USERS=username1,username2
```

The same GitHub OAuth app is also used by automations that need GitHub repository access. If `GITHUB_SSO` is not set to `true`, the OAuth app is available for automations but not as a login provider.

## Configure GitLab SSO

Enable GitLab as a login provider and let users connect a GitLab account to import repositories and open merge requests from [context recommendations](/nao-agent/context-engineering/recommendations).

1. Create an application in GitLab under **User Settings -> Access -> Applications**.
2. Add the callback URLs (replace `localhost:5005` with your deployment host):

```
https://<your-nao-host>/api/auth/callback/gitlab   # "Sign in with GitLab" (SSO)
https://<your-nao-host>/api/gitlab/callback         # "Connect GitLab" in settings
```

3. Grant the scopes `api`, `read_user`, `openid`, and `email`.
4. Set the following environment variables:

```bash theme={null}
GITLAB_CLIENT_ID=your-gitlab-client-id
GITLAB_CLIENT_SECRET=your-gitlab-client-secret
GITLAB_REDIRECT_URI=https://<your-nao-host>/api/gitlab/callback
```

5. Optional settings:

```bash theme={null}
GITLAB_SSO=true                          # expose GitLab as a login provider
GITLAB_BASE_URL=https://gitlab.example.com   # for a self-hosted GitLab instance
GITLAB_ALLOWED_USERS=username1,username2     # restrict sign-in to specific users
```

As with GitHub, if `GITLAB_SSO` is not set to `true`, the OAuth app is still available for connecting an account and opening merge requests, but not as a login provider.

## Set the project date format

Choose how dates are displayed across the project from **Settings -> Project**. The selected format applies everywhere dates render: chat tables and charts, stories, story exports (PDF/HTML), and messaging-channel replies (Slack, Teams, Telegram, WhatsApp).

Set it once at the project level so everyone on the team sees dates in a consistent format.

## Configure Slack integration

Connect your nao agent to Slack so your team can ask questions directly in Slack channels.

Configure Slack integration from the **Slack** section in the admin sidebar, or see the [Slack Bot guide](/nao-agent/connectors/slack) for detailed setup instructions.

## Choose LLM models

Configure which LLM providers and models are available to your agent.

**Configure API Keys**

In the **Models** section of the admin panel:

* **If no API key exists in your environment variables**: Enter your LLM API key directly in the UI
* **If an API key exists in your environment variables**: You can override it by entering a different key in the UI

<Info>
  Environment variables take precedence over UI configuration by default. Entering a key in the UI allows you to override the environment variable for that provider.
</Info>

**Azure OpenAI setup**

Use the **Azure OpenAI** provider when your Azure endpoint serves OpenAI-compatible models such as GPT.

1. Navigate to **Models** in the admin sidebar
2. Add or edit the **Azure OpenAI** provider
3. Enter your Azure API key
4. Configure either a **Resource Name** or a **Base URL**

Use **Resource Name** when your endpoint follows Azure OpenAI's standard format:

* Resource name: `my-resource`
* nao builds the URL as `https://my-resource.openai.azure.com/openai/v1`

Use **Base URL** when Azure gives you a full endpoint or you are going through a proxy:

* If Azure shows `https://my-resource.openai.azure.com/openai/v1/`, enter `https://my-resource.openai.azure.com/openai`
* Do not include the trailing `/v1` or a request path, because nao adds those automatically

Optional Azure OpenAI fields:

* **API Version**: Set this only if your Azure setup requires a specific version. Otherwise leave the default `v1`
* **Use Deployment-Based URLs**: Enable this only if your Azure deployment uses the legacy `/deployments/{deploymentId}` route style

For Azure OpenAI, the model ID in nao should match the deployment name you created in Azure.

You can also configure Azure OpenAI entirely via environment variables instead of the UI:

```bash theme={null}
AZURE_API_KEY=...
AZURE_RESOURCE_NAME=my-resource          # or AZURE_OPENAI_BASE_URL=https://my-resource.openai.azure.com/openai
AZURE_API_VERSION=v1                     # optional, defaults to v1
AZURE_USE_DEPLOYMENT_BASED_URLS=false    # optional, set to true only for legacy /deployments/{id} endpoints
```

The Azure OpenAI provider ships with an empty default model list, so you must add the deployment names you want to expose before users can pick them.

**Azure-hosted Anthropic setup**

If you deploy Claude through **Azure AI Foundry**, use the **Anthropic** provider in nao, not **Azure OpenAI**.

1. Navigate to **Models** in the admin sidebar
2. Add or edit the **Anthropic** provider
3. Enter your Azure AI Foundry API key
4. Set the **Base URL** to your Anthropic endpoint prefix

Example:

* If Azure shows a target URI such as `https://my-resource.services.ai.azure.com/anthropic/v1/messages`
* Enter `https://my-resource.services.ai.azure.com/anthropic/v1` in nao
* Do not include the trailing `/messages`, because the Anthropic API client adds it automatically

For Azure-hosted Claude models, the model ID in nao should match your Azure deployment name, for example `claude-sonnet-4-5`.

**AWS Bedrock Setup (Step-by-Step)**

Use one of these two authentication paths:

1. **Bearer token**

* Set `AWS_BEARER_TOKEN_BEDROCK`
* Optional: set `AWS_REGION` (defaults to `us-east-1`)
* In **Models**, add provider **AWS Bedrock**, then configure model IDs

2. **IAM credentials**

* Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
* Optional: set `AWS_SESSION_TOKEN` and `AWS_REGION` (defaults to `us-east-1`)
* In **Models**, add provider **AWS Bedrock**, then configure model IDs

For IAM credentials, you can leave the Bedrock API key field empty.

**Custom models**

When adding a model that isn't in a provider's default list (self-hosted endpoints, fine-tuned variants, preview models), click **Add custom model** to open the custom model dialog. You can set:

* **Display name** - a friendly label shown to users in the model picker (e.g. "GPT-4 Turbo (fine-tuned)")
* **Model ID** - the identifier your provider expects in API calls
* **Input token price** and **Output token price** - per-million-token costs used by the budget tracker

Custom pricing is optional. If left blank, the model won't appear in cost breakdowns.

**Select Available Models**

Control which models your users can access by providing the model ID from your LLM provider:

1. Navigate to **Models** in the admin sidebar
2. Add or edit a provider (Anthropic, Azure OpenAI, OpenAI, Google, Mistral, AWS Bedrock, or OpenRouter)
3. Enter the **model ID** for each model you want to make available
4. Users will only be able to select from the models you've configured

Model IDs are provider-specific. For example:

* Anthropic: `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-haiku-4`
* Azure OpenAI: use your Azure deployment name
* OpenAI: `gpt-4`, `gpt-4-turbo`, `gpt-3.5-turbo`
* Google: `gemini-3.1-pro-preview`, `gemini-2.0-flash-exp`, `gemini-1.5-pro`
* Mistral: `mistral-large-latest`, `mistral-medium-latest`
* AWS Bedrock: `us.anthropic.claude-sonnet-4-6`, `eu.anthropic.claude-opus-4-6-v1`
* OpenRouter: Various models from multiple providers

**Google Vertex AI (Claude models)**

If you access Claude through Google Vertex AI, use the **Google** provider and set the model ID to a `claude-*` model. nao automatically enables prompt caching for Claude models served through Vertex, using the same cache control mechanism as the direct Anthropic provider. No extra configuration is needed.

**Supported LLM Providers**

nao supports the following LLM providers:

* **Anthropic** - Claude models (prompt caching enabled automatically)
* **Azure OpenAI** - Azure-hosted OpenAI-compatible models
* **OpenAI** - GPT models
* **Google** - Gemini models and Claude models via Vertex AI (prompt caching enabled for Claude)
* **Mistral** - Mistral AI models
* **AWS Bedrock** - Claude and other models through Amazon Bedrock (supports bearer token or IAM credentials)
* **OpenRouter** - Access to multiple models from various providers through a single API

## Configure MCP Servers

Use MCP Servers to expose external tools (for example BI tools, internal APIs, or other systems) to the nao agent.

The actual server configuration lives in your nao-core project, in the `agent/mcps/mcp.json` file created by `nao init`. Once that file is present in the project linked to your deployment, you can manage it from the admin panel:

1. Navigate to **MCP Servers** in the admin sidebar.
2. See the list of MCP servers defined in your project.
3. Enable or disable individual MCP servers for this deployment.
4. Optionally restrict which tools from each server are exposed to users.

When a server is enabled, its tools become available to the agent as part of its toolset (see [Chat capabilities](/nao-agent/chat/capabilities/tools-mcps-skills#agent-tools)) and can be called automatically or via tool shortcuts in the chat UI.

## Configure nao MCP endpoint

Expose nao as an MCP server so external AI clients (Cursor, Codex, Claude Code, Claude Desktop, or any custom MCP client) can call the agent, run SQL, browse context, and manage stories.

For an overview of modes and tools, see [MCP Endpoint](/nao-agent/connectors/mcp).

**Step 1: Enable the endpoint**

1. Navigate to **Settings** -> **MCP Endpoint**.
2. Toggle **Enable MCP endpoint** on.
3. Enable the modes you want exposed: **Sub-agent mode**, **Context-layer mode**, or both. Story and chart tools are exposed automatically whenever either mode is on.
4. Copy the **Endpoint URL** and **Bearer token** from the **Connection guide** section.

**Step 2: Connect a client**

The connection guide on the settings page shows ready-to-paste snippets for each client. Replace `<your-endpoint-url>` and `<your-token>` with the values from your settings page.

<Tabs>
  <Tab title="Cursor">
    1. Open **Settings** -> **Tools & MCP**.
    2. Click **New MCP Server** and paste the JSON below, or edit `.cursor/mcp.json` manually.
    3. Authenticate in your browser when prompted.

    ```json theme={null}
    {
      "mcpServers": {
        "nao": {
          "type": "http",
          "url": "<your-endpoint-url>"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    1. Open **Settings** -> **MCP servers** -> **+ Add server** -> **Streamable HTTP**.
    2. Paste your endpoint URL into the URL field, then save.
    3. Authenticate in your browser when prompted.
  </Tab>

  <Tab title="Claude Code">
    1. Open `<your_project>/.mcp.json` (project root).
    2. Paste the config below.

    ```json theme={null}
    {
      "mcpServers": {
        "nao": {
          "type": "http",
          "url": "<your-endpoint-url>",
          "headers": {
            "Authorization": "Bearer <your-token>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    **Method 1 — via Settings UI**

    1. Open **Settings** -> **Connectors** -> **Add custom connector**.
    2. Set **Name** to anything, and **Remote MCP Server URL** to your endpoint URL.
    3. Enable the connector and authenticate in your browser.

    **Method 2 — via config file**

    1. Open `claude_desktop_config.json` (typically in `~/Library/Application Support/Claude/`).
    2. Add the server using the JSON below.
    3. Restart Claude Desktop and authenticate when prompted.

    ```json theme={null}
    {
      "mcpServers": {
        "nao": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "<your-endpoint-url>"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="CLI / Scripts">
    Use the config below in any MCP client that supports HTTP transport.

    ```json theme={null}
    {
      "mcpServers": {
        "nao": {
          "type": "http",
          "url": "<your-endpoint-url>",
          "headers": {
            "Authorization": "Bearer <your-token>"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Treat the Bearer token like a password. Do not commit it to source control and rotate it from the settings page if exposed.
</Warning>

## Configure Telegram

Use Telegram when you want users to message nao from the Telegram app.

1. Navigate to **Project** -> **Telegram**
2. Create a bot with `@BotFather`
3. Paste the **Bot Token** into nao
4. Save the form so nao registers the webhook automatically
5. Choose the model used for Telegram replies

Each user also gets a **Linking Code** on the Telegram page. They send that code to the bot once so nao can map their Telegram identity to the correct account.

For the full walkthrough, see [Telegram Bot](/nao-agent/connectors/telegram).

## Configure WhatsApp

Use WhatsApp when you want users to interact with nao from a WhatsApp number backed by a Meta app.

1. Navigate to **Project** -> **WhatsApp**
2. Paste the **Access Token**, **App Secret**, **Phone Number ID**, and **Verify Token**
3. Copy the **Webhook URL** from nao into your Meta webhook configuration
4. Save the form
5. Choose the model used for WhatsApp replies

Users link their identity by copying the **Linking Code** from the WhatsApp page and sending it to the bot.

For the full walkthrough, see [WhatsApp Bot](/nao-agent/connectors/whatsapp).

## Browse the context folder

Admins can inspect the synced context folder directly from the UI:

1. Navigate to **Settings** -> **File Explorer**
2. Browse the project tree on the left
3. Open a file to read it in the built-in viewer
4. Use search to quickly find context files

The file explorer is read-only and respects `.naoignore`, excluded directories, path validation, and a 1 MB read limit per file.

## Configure Template Prompts

Customize prompt suggestions for your users in the chat.
These prompts will be shown to your users in a new chat. These can be used to give your users examples of questions they can send to the chat.

1. Navigate to **Agent** in the admin sidebar
2. Look for **Template Prompts** section
3. Add example prompts that users can click to get started, such as:
   * "What were our top 5 products by revenue last month?"
   * "Show me user signups by country for the past quarter"
   * "Compare this month's sales to last month"
   * "What's the average order value by customer segment?"

These template prompts help users understand what types of questions they can ask and provide quick-start examples for common analytics queries.

## Context recommendations

nao can audit its own usage and recommend where your context needs work - which file to edit and what is missing. Review and configure them as an admin under **Settings -> Recommendations**:

* Recommendations are ordered by impact, each naming a target file and citing the originating chat and the model that produced it.
* **Acknowledge**, **snooze**, or **dismiss** each one as you work through them.
* Configure the **analysis model**, the **run frequency** (daily / weekly / monthly, or **Run now**), optional **custom audit instructions**, and the **GitHub repository** where fixes are opened as pull requests. Turn on **YOLO mode** to open those PRs automatically without review.

Enable the audit on your deployment by setting `BETA_CONTEXT_RECOMMENDATIONS_ENABLED=true`.

For the full workflow - what it scans, how it fits the evaluation feedback loop, and the GitHub pull-request flow - see [Recommendations](/nao-agent/context-engineering/recommendations).

**What's Next?**

<CardGroup cols={2}>
  <Card title="Admin Monitoring" icon="chart-line" href="/nao-agent/chat/admin/monitoring">
    Learn how to track usage, feedback, and costs
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/nao-agent/self-hosting/deployment-guide">
    Deploy nao chat to production with step-by-step instructions
  </Card>
</CardGroup>