getnao/nao repository overview

⁠nao - The #1 Open-Source Analytics Agent

nao is a framework to build and deploy analytics agents. Create context for your analytics agent with the nao-core CLI, then deploy a chat UI for anyone to interact with your data.

🌐 Website⁠ · 📚 Documentation⁠ · 💬 Slack⁠ · 🐙 GitHub⁠

⁠Docker

⁠Supported Tags

• latest - Latest stable release
• commit-hash - Specific commit hash tags

⁠Supported Architectures

• linux/amd64

⁠Base Image

• Python 3.12 (slim) with Node.js 24 and Bun

⁠Quick Start

⁠Using Docker Run (SQLite database)

docker run -d \
  --name nao \
  -p 5005:5005 \
  -e OPENAI_API_KEY=sk-... \
  -v /path/to/your/project:/app/project \
  getnao/nao:latest

⁠Environment Variables

* At least one LLM API key is required to make AI queries.

⁠Ports

⁠Volumes

Mount your nao project directory to make it available to the agent:

-v /path/to/your/nao-project:/app/project

Then set NAO_DEFAULT_PROJECT_PATH=/app/project, you can also use the example project by setting NAO_DEFAULT_PROJECT_PATH=/app/example.

⁠Docker run example

docker run -d \
  --name nao \
  -p 5005:5005 \
  -e NAO_DEFAULT_PROJECT_PATH=/app/project \
  getnao/nao:latest

Then navigate to http://localhost:5005⁠ to access the UI (or to any URL you configured).

⁠Git-based context

Instead of mounting a volume, you can have the container clone your nao project from a git repo on startup. This is a fully supported setup. Because it uses one shared credential, pull requests are opened by the account that owns the deployment token; commits still show the person who made each edit. Connecting GitHub in Settings → Git is recommended when pull requests should be opened as each user.

docker run -d \
  --name nao \
  -p 5005:5005 \
  -e OPENAI_API_KEY=sk-... \
  -e NAO_CONTEXT_SOURCE=git \
  -e NAO_CONTEXT_GIT_URL=https://github.com/your-org/your-nao-context.git \
  -e NAO_CONTEXT_GIT_BRANCH=main \
  -e NAO_CONTEXT_GIT_TOKEN=ghp_xxx \
  -e NAO_DEFAULT_PROJECT_PATH=/app/context \
  getnao/nao:latest

If your nao project lives inside a subfolder of a larger repo (e.g. a monorepo), set NAO_CONTEXT_GIT_SUBPATH and only that folder will be cloned via git sparse checkout:

-e NAO_CONTEXT_GIT_SUBPATH=analytics/finance

The container then expects nao_config.yaml at <NAO_DEFAULT_PROJECT_PATH>/<NAO_CONTEXT_GIT_SUBPATH>/nao_config.yaml.

When a token or SSH deploy key is configured, context admins can edit files and propose changes for review from the UI.

⁠Bitbucket HTTPS authentication

Use a repository, workspace, or project access token. Give it Repositories: Read and Write and Pull requests: Read and Write, then set only NAO_CONTEXT_GIT_TOKEN.

An Atlassian API token or legacy app password can instead be embedded in the URL: https://<email-or-username>:<token>@bitbucket.org/<workspace>/<repo>.git. nao uses those credentials for both Git and pull-request API calls.

⁠SSH deploy key authentication

For private repos, you can use a GitHub deploy key⁠ instead of a personal access token. Use the SSH URL ([email protected]:org/repo.git) and pass the private key contents via NAO_CONTEXT_GIT_SSH_KEY:

docker run -d \
  --name nao \
  -p 5005:5005 \
  -e OPENAI_API_KEY=sk-... \
  -e NAO_CONTEXT_SOURCE=git \
  -e [email protected]:your-org/your-nao-context.git \
  -e NAO_CONTEXT_GIT_SSH_KEY="$(cat ~/.ssh/nao_deploy_key)" \
  -e NAO_DEFAULT_PROJECT_PATH=/app/context \
  getnao/nao:latest

Enable Allow write access when creating a GitHub deploy key. It is off by default; without it, clones work but pushes fail. GitHub's host keys are pre-pinned, so SSH host verification is strict.

⁠Key Features

• 🧱 Open Context Builder — Create file-system context for your agent
• 🏳️ Data Stack Agnostic — Works with any data warehouse, stack, LLM
• 🔒 Self-hosted & Secure — Use your own LLM keys for maximum data security
• 🤖 Natural Language to Insights — Ask questions in plain English
• 📊 Native Data Visualization — Create visualizations directly in chat

⁠License

Apache 2.0 - See LICENSE⁠