• English

      • AI Agent Integration Guide

      NocoBase fully supports AI Agent collaboration — you can use natural language to complete data modeling, page building, workflow orchestration, permission configuration, and even custom plugin development. Whether you use Claude Code, Codex, Cursor, or other AI tools, you can work with NocoBase through these two foundational components:

      1. NocoBase CLI — A command-line tool for initializing, connecting to, and managing NocoBase applications in your local workspace. It helps you prepare NocoBase applications, save CLI env configurations, and provides daily management commands such as start, stop, view logs, upgrade, and clean up — enabling AI Agents to connect and use NocoBase.

      CLI supports two common initialization methods:

      • Connect to an existing NocoBase application so that AI Agents can use it directly.
      • Install a new NocoBase application via Docker, npm, or Git, and save it as a CLI env.
      1. NocoBase Skills — Domain knowledge packages that enable AI Agents to understand NocoBase's configuration system and development conventions. They cover data modeling, UI configuration, workflow management, permission configuration, plugin development, and more. NocoBase CLI automatically installs Skills during initialization (nb init), so no manual installation is needed.

      Once you install CLI and complete initialization, your AI Agent can directly operate your NocoBase application.

      Prerequisites

      Before getting started, make sure the following environment requirements are met:

      • Node.js >= 22
      • Yarn 1.x
      • We recommend using AI Agents powered by leading large models such as Claude or GPT. Results depend heavily on the model used — for the best experience, choose the latest flagship model available.

      Install a New NocoBase and Connect AI Agent

      If you already have a running NocoBase instance, you can skip to the next section: Connect AI Agent to an Existing NocoBase.

      If you don't have a NocoBase application yet, you can use CLI to install and initialize a new NocoBase application, then connect AI Agent to it.

      Manual Installation and Connection
      Install and Connect with AI Agent

      Step 1: Install CLI

      npm install -g @nocobase/cli@beta
nb --version // Confirm successful installation

      Step 2: Initialize

      nb init --ui
      Configuration file storage

      Configuration files and application data are stored in your home directory by default. See NB_CLI_ROOT environment variable for details.

      The browser will automatically open a visual configuration page, guiding you through 5 steps:

      1. Start Configuration — Set the application name (also used as the CLI environment name), select "Fresh Installation"
      2. Create Application — Choose the installation method (Docker / npm / Git), set port and other basic configurations
      3. Download Application Files — Select source and version, download NocoBase source code or image
      4. Configure Database — Use the built-in database or configure an external database (PostgreSQL, MySQL, MariaDB)
      5. Create Admin Account — Set the admin email and password

      nocobase cli visual wizard

      After installation is complete, open your browser and visit http://localhost:13000 (default port), then log in with the admin account you just set up.

      (If you prefer working in the command line, you can also run nb init to enter the interactive wizard, or nb init --env=app -y to use default configuration with one command.)

      Step 3: Let AI Agent Start Working

      Start a new or restart the AI Agent session, and you can let the AI Agent start operating NocoBase. CLI configuration is stored in a global directory (default ~/.nocobase/), accessible from any directory.

      Connect AI Agent to an Existing NocoBase

      If you already have a running NocoBase instance, you can connect AI Agent to it directly. Since AI capabilities are evolving rapidly, only the latest beta version provides the full experience. The minimum required version is 2.1.0-beta.20 — we strongly recommend updating to the latest.

      Manual Connection
      Connect with AI Agent

      Step 1: Install CLI

      npm install -g @nocobase/cli@beta
nb --version // Confirm successful installation

      Step 2: Initialize and Connect

      nb init --ui
      Configuration file storage

      Configuration files are stored in your home directory by default. See NB_CLI_ROOT environment variable for details.

      The browser will automatically open a visual configuration page. In the first step "Start Configuration", select "Connect to Existing Application", then:

      1. Enter API Address — Input the API address of your existing NocoBase instance (e.g., http://localhost:13000/api)
      2. Select Authentication Method — Choose an authentication method (OAuth is recommended for quick setup)

      nocobase cli visual wizard

      No need to configure installation method, database, or admin account — the wizard will skip those steps.

      Step 3: Let AI Agent Start Working

      Start a new or restart the AI Agent session, and you can let the AI Agent start operating NocoBase. CLI configuration is stored in a global directory (default ~/.nocobase/), accessible from any directory.

      What's Next

      Manage Application Environments

      If you need to manage existing NocoBase instances (such as test or production environments), or switch between multiple environments, see Environment Management — covering environment checks, adding environments, upgrades, and troubleshooting.

      Start AI Building

      Describe your requirements in natural language, and AI helps you complete data modeling, page building, and workflow orchestration — replace manual configuration with conversation. See AI Building Quick Start.

      Continue with AI Plugin Development

      If you need to develop custom plugins, AI can help too — from scaffolding generation to component code and business logic, covering the full plugin development process. See AI Plugin Development.

      Use AI Employees

      Collaborate with AI employees directly in the NocoBase interface — data analysis, report generation, translation, decision support, without leaving your business system. See AI Employees.

      NocoBase CLI Command Reference

      If you already have a NocoBase application running, or have successfully completed initialization and want to continue developing, debugging, or managing your application, see NocoBase CLI Command Reference for full parameter documentation of all nb commands.