Skip to main content

​
Step 1: Install nao-core package

Drive setup from your agentic CLI. If you use Claude Code, Codex, Cursor, or any other agent that loads SKILL.md files, you can install the published nao skills and have the agent walk you through Steps 2–6 interactively:
Then ask the agent to “use the setup-context skill”. See Skills for what each one does and when to use it.

​
Step 2: Initialize a nao project

This command will ask you:
  • To name your project (defaults to the current folder name - press Enter to accept)
  • If you want to connect a database (optional)
  • If you want to set up an LLM (optional)
  • If you want to add a git repository to the agent context (optional)
You can skip any optional question and configure it later in your nao_config.yaml file. Slack, Notion, MCP servers, and skills are no longer prompted during nao init - add them directly in nao_config.yaml.

​
Non-interactive mode

For CI pipelines or agentic workflows (Claude Code, Cursor, Codex), run nao init without any prompts:
In --yes mode:
  • If nao_config.yaml already exists, it is reused as-is and only the folder structure is scaffolded.
  • If no config exists, a minimal one is created with the project name (from --name or the current directory name).
  • Databases, LLM, and integrations are not configured. Edit nao_config.yaml afterward or use the setup-context skill.
This will create:
  • A new folder with your project name
  • An architecture for your context files
  • A nao_config.yaml configuration file
  • A RULES.md file
  • A tests/ folder with a starter test_example.yml test file

​
Step 3: Verify your setup

cd to the project folder and run:
This command checks your configuration and displays any issues. It tests every database declared in nao_config.yaml, then tests each LLM provider listed under llm.providers. Connection checks are available for OpenAI, Anthropic, Gemini, Mistral, OpenRouter, Ollama, AWS Bedrock, and Google Vertex.
  • Ollama: lists the models available on the local Ollama instance.
  • AWS Bedrock: reports the resolved region, then lists foundation models using your aws_profile / AWS_PROFILE credentials. If a bearer token is set as the API key, nao reports it as configured without listing models.
  • Google Vertex: reports the resolved gcp_project and gcp_location and the credential source it picked up (service account JSON, key file, or application default credentials). It fails if gcp_project is not set.
If you set base_url on a provider to point at an OpenAI-compatible proxy such as LiteLLM, nao debug uses that base URL for the connectivity test instead of the provider default, so the check reflects the endpoint your agent actually calls. This applies to the openai, anthropic, and openrouter providers.

​
Step 4: Synchronize your context

This will populate your context folder with your context files (data, metadata, repos, etc.).

​
Step 5: Launch the chat and ask questions

You have two options to access the chat UI:

​
Option 1: Using nao chat command

This will start the nao chat UI. It will open the chat interface in your browser at http://localhost:5005.

​
Option 2: Using Docker

Instead of nao chat, you can use Docker to run the UI: With built-in example:
With your project:
Access the UI at http://localhost:5005 and add your LLM API key in the settings. From there, you can start asking questions to your agent!

​
Step 6: Evaluate your agent

nao init scaffolds a starter test file at tests/test_example.yml. You can add more test files with questions and expected SQL in YAML format, then measure your agent’s performance:
View results in tests panel:

Evaluation Guide

Learn how to build comprehensive test suites and evaluate your agent

​
What’s Next?

Skills

Install five published skills to let your agentic CLI automate setup, rules, tests, and audits

Context Builder

Learn how to build and customize your agent’s context

Self-Hosting

Deploy your agent in production

Chat Interface

Explore the chat interface features

nao Cloud

Use our managed cloud service