How to Set Up a Development Environment for AiToEarn: Complete Monorepo Guide

Clone the repository, install dependencies with pnpm, copy configuration templates to local files, and run the NestJS backend services (aitoearn-ai on port 3001 and aitoearn-server on port 3000) alongside the Next.js frontend (port 4000) to get the full AiToEarn stack running locally.

AiToEarn is an AI-powered content creation platform organized as an Nx monorepo using pnpm. Setting up a development environment for AiToEarn requires coordinating multiple services including a NestJS backend, Next.js frontend, and optional Electron desktop client. This guide provides the exact commands and file paths from the yikart/AiToEarn repository to get everything running locally.

Prerequisites

Before starting, ensure you have the following installed:

• Node.js (LTS version recommended)
• pnpm (the monorepo uses pnpm-lock.yaml for deterministic installs)
• Docker (optional, for running MongoDB and Redis)
• Git

Clone the Repository

Start by cloning the repository and navigating to the project root:

git clone https://github.com/yikart/AiToEarn.git
cd AiToEarn

Configure and Run the Backend Services

The backend resides in project/aitoearn-backend and consists of two primary NestJS applications: the AI agent service (aitoearn-ai) and the public API server (aitoearn-server).

Install Backend Dependencies

cd project/aitoearn-backend
pnpm install

Copy Configuration Templates

You must create local configuration files by copying the production templates:

cp apps/aitoearn-ai/config/config.js apps/aitoearn-ai/config/local.config.js
cp apps/aitoearn-server/config/config.js apps/aitoearn-server/config/local.config.js

The files apps/aitoearn-ai/config/config.js and apps/aitoearn-server/config/config.js contain production defaults. The local.config.js files allow you to override settings like MongoDB connection strings and API keys without modifying tracked files.

Start the AI Agent Service

Run the AI service on port 3001 using Nx:

pnpm nx serve aitoearn-ai

This command uses Nx's dev server with hot-reload enabled, automatically watching source files in the workspace defined by nx.json.

Start the API Server

In a second terminal, start the public API server on port 3000:

pnpm nx serve aitoearn-server

Start the Frontend Application

The web UI is located in project/aitoearn-web and consumes the backend APIs. From the repository root:

cd project/aitoearn-web
pnpm install
pnpm run dev

The Next.js application starts on port 4000 by default. It connects to http://localhost:3000 for the API server and uses the client SDK from project/aitoearn-backend/libs/aitoearn-server-client for type-safe API calls.

Run Supporting Services with Docker

Instead of installing MongoDB and Redis locally, use the Docker Compose configuration at the repository root:

docker compose -f docker-compose.yml up -d mongo redis

This starts MongoDB on port 27017 and Redis on port 6379. Update your local.config.js files in the backend apps to point to these instances if you are not using the default localhost configuration.

Build the Electron Desktop Client (Optional)

For the desktop application wrapper located in project/aitoearn-electron:

cd project/aitoearn-electron
npm install
npm run rebuild
npm run dev

Note that the Electron workspace uses npm rather than pnpm. The npm run rebuild command compiles native SQLite bindings required for the local database functionality. The desktop client bundles the same Next.js build and adds native features like auto-updates (logic found in project/aitoearn-electron/src/components/update/).

Monorepo Architecture Overview

Understanding the structure helps when navigating the codebase:

• project/aitoearn-backend: Contains the NestJS monorepo with shared libraries under libs/ (including aitoearn-auth, aitoearn-queue, and aitoearn-server-client). The AI agent engine implements modular skills under apps/aitoearn-ai/src/core/agent/skills/.
• project/aitoearn-web: Next.js frontend with Redux store management for AI agents (see src/store/agent/).
• project/aitoearn-electron: Desktop wrapper using Vite and Electron that loads the web bundle and provides native SQLite storage.

Summary

• Clone the repository and use pnpm for all workspaces except Electron, which requires npm
• Copy configuration templates to local.config.js in both apps/aitoearn-ai/config/ and apps/aitoearn-server/config/ before running services
• Run aitoearn-ai on port 3001 and aitoearn-server on port 3000 using pnpm nx serve
• Start the Next.js frontend on port 4000 with pnpm run dev from project/aitoearn-web
• Use Docker Compose to run MongoDB and Redis if not installed locally
• Build the Electron client with npm run rebuild to compile native dependencies before running npm run dev

Frequently Asked Questions

Do I need to run both backend services to develop the frontend?

Yes, the Next.js frontend in project/aitoearn-web expects both the AI agent service (port 3001) and the API server (port 3000) to be running. The web application imports the client SDK from project/aitoearn-backend/libs/aitoearn-server-client, which attempts to connect to both endpoints. Many UI components in the agent store (src/store/agent/) depend on endpoints from both servers to function correctly.

Why does the Electron project use npm instead of pnpm?

The Electron workspace uses npm because certain native dependencies, particularly the SQLite bindings, require specific rebuild scripts that are configured for npm. Running npm run rebuild ensures the native modules compile correctly against the Electron runtime. Using pnpm can interfere with native module paths due to its content-addressable symlinking strategy, which is why the repository explicitly uses npm for the aitoearn-electron workspace.

How do I add a new AI skill to the development environment?

Create a new folder under project/aitoearn-backend/apps/aitoearn-ai/src/core/agent/skills/ following the existing structure. Include a SKILL.md file describing inputs, outputs, and implementation details, then register the skill in src/core/agent/skills/index.ts. The NestJS dev server watches source files and automatically hot-reloads when you add or modify skills.

Can I change the default ports for development?

Yes, edit the local.config.js files in apps/aitoearn-ai/config/ and apps/aitoearn-server/config/ to modify the port variables. For the frontend, create a .env.local file in project/aitoearn-web to override NEXT_PUBLIC_API_URL and other environment variables. The layout configuration at src/app/layout/README.md documents additional environment variables used by the Next.js application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}