ContextQMD
Back to Nocobase

AI Agent Integration Guide

docs/docs/en/ai/quick-start.mdx

2.1.08.8 KB
Original Source

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.

import { Tab, Tabs } from '@rspress/core/theme';

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.

<Tabs> <Tab label="Manual Installation and Connection" value="manual-install">

Step 1: Install CLI

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

Step 2: Initialize

bash
nb init --ui

:::tip 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

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.

</Tab> <Tab label="Install and Connect with AI Agent" value="ai-install">

Copy the prompt below to your AI assistant (Claude Code, Codex, Cursor, Trae, etc.), and it will complete CLI installation and guide you through initializing a new NocoBase:

Help me install NocoBase CLI and complete initialization: https://docs.nocobase.com/ai/ai-quick-start.md (please read the linked content directly)

After configuration is complete, restart your AI Agent session and you can start operating NocoBase.

</Tab> </Tabs>

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.

<Tabs> <Tab label="Manual Connection" value="manual-connect">

Step 1: Install CLI

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

Step 2: Initialize and Connect

bash
nb init --ui

:::tip 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)

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.

</Tab> <Tab label="Connect with AI Agent" value="ai-connect">

Copy the prompt below to your AI assistant. It will complete CLI installation and guide you through connecting to your existing NocoBase instance. Select "Connect to Existing Application" in the first step of the visual wizard:

Help me install NocoBase CLI and complete initialization: https://docs.nocobase.com/ai/ai-quick-start.md (please read the linked content directly)

After configuration is complete, restart your AI Agent session and you can start operating NocoBase.

</Tab> </Tabs>

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.