How to Deploy NocoBase with Claude AI Coding Agents on Docker 2025

NocoBase combines open-source infrastructure with AI-powered development, letting Claude or other coding agents scaffold your business systems while you refine them visually. This hybrid approach eliminates the friction of pure no-code platforms or starting from scratch with traditional development.

In this guide, you'll set up NocoBase locally with Docker, integrate it with Claude AI agents, and deploy a working business system in under an hour.

Why NocoBase with AI Agents Matters

Traditional no-code platforms force you to build everything manually in a UI. Pure code-first approaches require scaffolding and setup time. NocoBase bridges both:

• AI agents handle boilerplate: Claude can set up data models, migrations, and API routes
• You refine visually: Switch to WYSIWYG mode to adjust UI and workflows without leaving the platform
• Production-ready from day one: Built on proven infrastructure, not experimental abstractions

This is fundamentally different from Airtable, Notion, or Webflow. You're not replacing developers—you're augmenting them with agents that understand your codebase.

Prerequisites

• Docker and Docker Compose installed (version 20.10+)
• Claude API access (via Anthropic) or Cursor IDE with local agent support
• Node.js 18+ (if running NocoBase outside Docker)
• A text editor or IDE with Claude integration (Cursor, VS Code with Cline extension)
• 2GB free disk space

Step 1: Clone and Verify NocoBase Repository

Start by getting the official NocoBase repository:

git clone https://github.com/nocobase/nocobase.git
cd nocobase
git checkout main  # Ensure you're on the latest stable branch

Verify the repo structure:

ls -la
# You should see: docker-compose.yml, packages/, README.md, etc.

NocoBase's monorepo structure is agent-friendly—Claude can navigate it to understand data models, API plugins, and workflow definitions without manual explanation.

Step 2: Launch NocoBase with Docker Compose

NocoBase provides a pre-configured docker-compose.yml for local development. This eliminates environment inconsistencies:

docker-compose up -d

This starts:

• NocoBase app on http://localhost:3000
• PostgreSQL database (production-ready)
• Redis cache (for performance)

Verify services are running:

docker-compose ps
# Should show: nocobase_app, nocobase_db, nocobase_redis all with status "Up"

Check logs if containers fail to start:

docker-compose logs nocobase_app

The app takes 30–60 seconds to initialize migrations on first run.

Step 3: Access NocoBase and Create Initial Setup

Open http://localhost:3000 in your browser. You'll see:

1. Initial setup wizard requesting admin email and password
2. Option to create a workspace
3. Dashboard with blank project canvas

Create an admin account and a workspace. This gives you a clean slate for AI agent collaboration.

Step 4: Prepare Your Codebase for Claude AI Agents

Claude agents work best when they understand your project structure. Create a .nocobase-agent.md file in the root:

# NocoBase Project Structure

## Key Directories
- `/packages/core`: Core business logic
- `/packages/plugins`: Plugin system for extensions
- `/packages/schemas`: Data model definitions
- `/apps/nocobase`: Main application

## How to Use Me (Claude Agent)
1. Review existing data models in `/packages/schemas`
2. Create new tables via the NocoBase API at `http://localhost:3000/api`
3. Add workflows in the WYSIWYG interface after scaffolding
4. Never modify `/packages/core` without testing

## Common Tasks I Handle
- Setting up PostgreSQL migrations
- Creating API endpoints for custom business logic
- Integrating plugins (e.g., auth, file storage)
- Scaffolding CRUD operations

This helps Claude understand where to work and what APIs to use.

Step 5: Integrate Claude with Your NocoBase Instance

Use Cursor IDE (built-in Claude agent support) or VS Code with Cline:

Option A: Cursor IDE

1. Open your NocoBase folder in Cursor
2. Press Cmd+K (macOS) or Ctrl+K (Linux/Windows) to open the agent chat
3. Paste this prompt:

I'm building a business system in NocoBase. My app is running on http://localhost:3000.

Create a data model for a Customer Management System with:
- Customer table (name, email, phone, status)
- Orders table (customer_id, total, created_at)
- Relationships: One customer has many orders

First, review the existing NocoBase API docs to understand the correct schema format.
Then, generate the API calls needed to create these tables.
Do NOT modify any existing files—just provide the API requests.

Claude will analyze your codebase and generate curl commands or Node.js code to set up your schema.

Option B: VS Code with Cline Extension

1. Install the Cline extension from the marketplace
2. Create a .cline-rules.md:

You are helping build a NocoBase application.

Rules:
1. NocoBase API base: http://localhost:3000/api
2. All table creation calls go through POST /tables
3. Foreign keys use "associations" in the schema
4. Test all generated code with curl or Postman before suggesting
5. Never write shell scripts that delete data

3. Open Cline and ask the same customer system prompt above

Step 6: Execute Agent-Generated API Calls

Once Claude generates API calls, execute them via curl or Postman:

curl -X POST http://localhost:3000/api/tables \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customers",
    "fields": [
      { "name": "name", "type": "string", "required": true },
      { "name": "email", "type": "email", "required": true },
      { "name": "phone", "type": "string" },
      { "name": "status", "type": "select", "options": ["active", "inactive"] }
    ]
  }'

Refresh NocoBase (http://localhost:3000) and you'll see the new table appear in the WYSIWYG editor.

Step 7: Refine with the WYSIWYG Interface

Switch to configuration mode in NocoBase:

1. Click the Settings icon (gear icon) in the top-right
2. Go to Data Models → Tables
3. Adjust field visibility, add validation rules, create views
4. Set up workflows (e.g., "send email when status changes")

This is where humans take over. The WYSIWYG interface is optimized for non-developers, so you can hand off UI refinement without going back to code.

Step 8: Deploy to Production

When you're ready to go live, stop the local Docker containers and deploy using a cloud provider:

docker-compose down

For production, use managed PostgreSQL (AWS RDS, DigitalOcean, Render) instead of containerized Postgres. Update your .env:

DB_HOST=your-prod-db.example.com
DB_PORT=5432
DB_USERNAME=produser
DB_PASSWORD=securepassword
DB_DATABASE=nocobase_prod

Run migrations on the production database:

docker run --env-file .env nocobase/nocobase npm run db:migrate

Then deploy the NocoBase container to Render, DigitalOcean App Platform, or Vercel.

Comparison: NocoBase vs Traditional Approaches

| Feature | NocoBase + AI Agents | Pure No-Code (Airtable) | Traditional Dev | |---------|---------------------|------------------------|----------------| | AI scaffolding | ✅ Claude agents | ❌ No agent support | ✅ GitHub Copilot | | Customization | ✅ Full API access | ⚠️ Limited | ✅ Unlimited | | Time to MVP | 1–2 weeks | 2–4 weeks | 4–8 weeks | | Cost at scale | 💰 Free (open-source) | 💰💰 Per-seat pricing | 💰💰💰 Engineers | | Version control | ✅ Git | ❌ No Git | ✅ Git | | AI integration | ✅ Built-in AI employees | ❌ Manual | ⚠️ API-dependent |

Common Issues and Solutions

Issue: Docker containers fail to start

Solution: Check port conflicts:

lsof -i :3000
kill -9 <PID>

Issue: Claude agent doesn't understand table relationships

Solution: Provide NocoBase schema examples in your agent prompt:

Example relationship in NocoBase:
{
  "name": "orders",
  "associations": [
    { "type": "belongsTo", "targetTable": "customers", "foreignKey": "customerId" }
  ]
}

Issue: API calls return 401 Unauthorized

Solution: Generate an API token in NocoBase settings:

1. Go to Settings → API
2. Create a new API key
3. Add header: Authorization: Bearer YOUR_TOKEN

Next Steps

1. Document your workflows: Create a wiki page explaining how Claude agents should extend your system
2. Set up GitHub Actions: Automate testing of agent-generated schema changes
3. Iterate: Let Claude handle new data model requests, refine in the UI
4. Monitor: Use NocoBase's built-in audit logs to track changes made by agents

By combining NocoBase's production-ready infrastructure with Claude's coding intelligence, you're not replacing developers—you're multiplying their output while keeping full control over the final system.

Resources

• NocoBase Docs: https://docs.nocobase.com/
• NocoBase API Reference: https://docs.nocobase.com/api
• Cursor AI IDE: https://cursor.com/
• Anthropic Claude API: https://console.anthropic.com/
• NocoBase GitHub: https://github.com/nocobase/nocobase