The NanoAgent handbook

Install

Desktop app

Download the latest release for your platform:

Release downloads are published at:

https://github.com/getnanoai/NanoAgent/releases/latest

CLI

Curl

curl -fsSL https://raw.githubusercontent.com/getnanoai/NanoAgent/master/scripts/install.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/getnanoai/NanoAgent/master/scripts/install.ps1 | iex

NPM

npm install -g nanoai-cli

pnpm

pnpm add -g nanoai-cli

bun

bun add -g nanoai-cli

First run & provider setup

Start NanoAgent:

nanoai

NanoAgent will guide you through provider setup:

1. Choose a setup type: subscription account, API key provider, OpenAI-compatible provider, or local provider.
2. Choose a provider from the matching submenu when needed.
3. Enter an API key, sign in with ChatGPT Plus/Pro, Claude Pro/Max, or GitHub Copilot, enter a custom compatible base URL, or use a local provider default.
4. Let NanoAgent discover available models.
5. Open a desktop workspace or use the current terminal directory.
6. Start a new section or resume an existing one.

Desktop workflow

The desktop app is built around workspaces, sections, chat, and controls.

Workspaces

Open a local folder to make it the active workspace. NanoAgent remembers recent workspaces so you can return later.

Sections

A section is a saved local conversation thread tied to a workspace.

Conversation

Type a prompt and let NanoAgent inspect, plan, edit, run commands, or ask for approval depending on the active profile and permissions.

Budget controls

Budget controls are disabled by default. They become active only after you enable them with /budget local or /budget cloud.

Terminal workflow

Interactive mode

nanoai

One-shot prompt

nanoai "Find risky changes in this branch"

Prompt from standard input

git diff --stat | nanoai --stdin --profile review

Terminal input & keys

The interactive terminal UI adds keyboard controls for editing, navigating history, queueing work, and interrupting a running turn.

Queue prompts and commands

You can queue prompts while NanoAgent is busy. Queued items run automatically, in order, as soon as the active turn completes.

Interrupt a running or stuck turn

Press Esc once to request a graceful interrupt. Press Esc again to abandon it locally.

Tab-complete file and directory paths

After a ! or !! shell command and a space, Tab completes file and directory paths.

Terminal commands

VS Code extension

NanoAgent includes a VS Code extension. Install from the Visual Studio Marketplace:

ext install rizwan3d.nanoagent

Visual Studio extension

NanoAgent includes a Visual Studio extension. It opens a tool window inside Visual Studio and starts the local NanoAgent CLI over ACP.

ACP editor integration

NanoAgent can run as an Agent Client Protocol server:

nanoai --acp

ACP mode speaks line-delimited JSON-RPC on stdin/stdout.

Review automation (CI)

NanoAgent includes copy-paste CI examples for GitHub, GitLab, and Bitbucket. Each example installs NanoAI, computes the diff, runs the workspace pr-reviewer profile in read-only mode, and posts a review comment.

Codebase indexing

NanoAgent includes a local codebase index for repository-wide discovery. The codebase_index tool can search, build, list, and show status.

Providers & models

NanoAgent stores a provider profile locally and discovers models from that provider. Use F2 or /models to switch.

Thinking mode

/thinking on\n/thinking off

Profiles & subagents

Code intelligence (LSP)

code_intelligence discovers language servers from built-in definitions, the current workspace, and optional profile overrides.

Permissions & sandboxing

NanoAgent evaluates every sensitive action through permission policy.

Sandbox modes

Workspace files

Run /init. NanoAgent asks which starter files to add.

Place AGENTS.md in the workspace for persistent project instructions.

Team memory

NanoAgent stores structured team memory as ordinary markdown files in .nanoagent/memory/.

Skills & custom agents

Skills are task-specific playbooks loaded only when relevant.

MCP servers

NanoAgent can load MCP servers from user-level and workspace-level agent-profile.json files.

Custom tools

NanoAgent can expose user-defined process tools from agent-profile.json.

Memory, audit & hooks

Configure memory, audit, and lifecycle hook behavior in workspace profile.

Privacy & local data

Workspace files, configuration, sections, codebase index cache, team memory, and audit logs stay on your machine.

Troubleshooting

nanoai is not found

Restart the terminal after installation.

Provider setup is incomplete

Run nanoai and choose to reconfigure.

A command is denied

Run /permissions and /rules to see active policy.

NuGet SDK (.NET)

The NanoAgent package on NuGet.org provides the core libraries. Add it to your project:

dotnet add package NanoAgent

Build from source

Requirements

• .NET SDK compatible with net10.0.
• Node.js 20 or newer for the VS Code extension.

dotnet restore NanoAgent.CrossPlatform.slnx
dotnet build NanoAgent.CrossPlatform.slnx
dotnet test NanoAgent.Tests/NanoAgent.Tests.csproj
dotnet pack NanoAgent/NanoAgent.csproj -c Release

License

NanoAgent is licensed under the Apache License 2.0.

Gateway Setup & Connection

NanoAgent Gateway is the central control plane for engineering teams. It provides a single endpoint (https://app.getnanoai.com/v1) to track model spend, set team budgets, and audit AI usage.

How to connect NanoAgent (Zero Code)

You don't need to write any code to use the Gateway with NanoAgent. Simply configure it in your terminal or IDE:

Method 1: Interactive Setup

nanoai setup

Select Gateway from the provider list and paste your Gateway API key.

Method 2: Environment Variable

export NANOAGENT_API_KEY="your_gateway_key_here"

Connecting Custom Apps & Scripts (Optional)

If your team has existing Python or Node.js scripts using OpenAI, you can point them to the Gateway by setting the standard OPENAI_BASE_URL:

export OPENAI_BASE_URL="https://app.getnanoai.com/v1"
export OPENAI_API_KEY="your_gateway_key_here"

Any library (OpenAI SDK, LangChain, Vercel AI SDK, LlamaIndex) will now route through the Gateway without changing code.

Gateway Dashboard & Spend Controls

Team leads and administrators manage the Gateway via the web dashboard at app.getnanoai.com:

• Spend Attribution: See exactly how much each team member or project spends on AI models in real time.
• Monthly Budget Caps: Set dollar limits per developer to prevent accidental overuse.
• Model Access Rules: Choose which models (Claude 3.7, GPT-4o, DeepSeek, Local Ollama) developers can use.
• Security Audit Logs: Review timestamped logs of all API activity for compliance.

NanoForge App Builder

NanoForge turns natural language prompts into full-stack web applications (React frontend + Express API + PostgreSQL database).

How to build an app

1. Go to NanoForge and type what you want to build (e.g. "Project dashboard with tasks, auth, and dark mode").
2. Click Build. NanoForge generates the code, sets up the database schema, and spins up a live container.
3. Interact with your live running app in the preview browser tab.

Extending NanoForge Apps Locally

Every NanoForge app is backed by a standard Git repository:

• Inspect Git Diffs: Review every commit generated by your prompts on GitHub before merging.
• Open in NanoAgent: Clone the repository to your machine and run nanoai to continue coding, testing, and adding features locally.