How to Set Up the AiToEarn Project Locally: Complete Development Guide

To set up AiToEarn locally, clone the yikart/AiToEarn repository, install Node.js 20.18.x and pnpm, start MongoDB and Redis via Docker, copy and edit the local.config.js files for both backend services, then launch the AI Agent and API server using pnpm nx serve, and finally start the Next.js frontend with pnpm run dev.

AiToEarn is an Nx-managed monorepo built with pnpm that separates its NestJS-based backend services from its Next.js frontend. This guide walks through the source development setup documented in the official repository, covering the exact file paths and commands needed to run the full stack on your local machine.

Prerequisites

Before cloning the repository, ensure your environment meets these requirements:

• Node.js version 20.18.x or higher, as specified in the project's engine constraints
• pnpm package manager (enable via corepack enable && corepack prepare pnpm@latest --activate)
• Docker and Docker Compose for running MongoDB and Redis locally
• Git for version control

If pnpm is not available through corepack, install it globally with npm i -g pnpm.

Clone the Repository and Initialize Dependencies

Start by cloning the monorepo into your working directory:

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

The repository root contains documentation and Docker orchestration files only. All source code resides inside the project/ directory, which contains separate workspaces for the backend, frontend, and optional Electron client.

Configure and Start the Backend Services

The backend is an Nx workspace located at project/aitoearn-backend. It manages two primary applications: aitoearn-ai (the AI Agent for model interactions) and aitoearn-server (the unified HTTP API).

Install Backend Dependencies

Navigate to the backend workspace and install packages using pnpm:

cd project/aitoearn-backend
pnpm install

The workspace configuration is defined in project/aitoearn-backend/pnpm-workspace.yaml and project/aitoearn-backend/nx.json, which map the applications and shared libraries.

Configure Local Environment Files

Both backend applications use a configuration override system. Copy the default configuration files to create local development versions:

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

Edit local.config.js in each app directory to point to your local MongoDB and Redis instances. By default, the Docker Compose setup exposes MongoDB at mongodb://mongo:27017/aitoearn and Redis at redis://redis:6379.

Launch the AI Agent and API Server

Open two separate terminal windows to run both services concurrently. The Nx CLI handles the build and serve process for each application.

Start the AI Agent service:

pnpm nx serve aitoearn-ai

This command launches the agent on http://localhost:3001 by default, handling content generation and transaction logic.

In a second terminal, start the unified API server:

pnpm nx serve aitoearn-server

The API server listens on http://localhost:3000 and provides the HTTP endpoints, OAuth relay, and SSE/MCP interfaces that the frontend consumes.

Start the Next.js Frontend

The web frontend is a standard Next.js application located in project/aitoearn-web.

Install dependencies and start the development server:

cd ../../aitoearn-web
pnpm install
pnpm run dev

The frontend development server typically starts on http://localhost:3000. If port 3000 is occupied by the backend API server, Next.js will automatically increment to the next available port (e.g., 3002).

Create a .env.local file in project/aitoearn-web to configure the API connection:

NEXT_PUBLIC_API_BASE=http://localhost:3000
NEXT_PUBLIC_API_KEY=your-local-api-key

(Optional) Run the Electron Desktop Client

For desktop functionality with offline SQLite storage, you can also run the Electron client located at project/aitoearn-electron.

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

The npm run rebuild step compiles native modules such as better-sqlite3 for your local Node.js version.

Provision Local Databases with Docker

If you do not have MongoDB and Redis installed locally, use the provided Docker Compose configuration at the repository root:

docker compose up -d mongo redis

This command starts the following services in detached mode:

• MongoDB on port 27017
• Redis on port 6379

The docker-compose.yml file also optionally includes Mongo Express for database visualization. Ensure your local.config.js files reference these Docker service names as hostnames (e.g., mongo and redis) when running the backend services within Docker networks, or use localhost when running them directly on the host machine.

Complete Local Development Workflow

To run the full stack simultaneously, use multiple terminal sessions or a terminal multiplexer like tmux:

Terminal 1 – AI Agent service:

cd project/aitoearn-backend && pnpm nx serve aitoearn-ai

Terminal 2 – API Server:

cd project/aitoearn-backend && pnpm nx serve aitoearn-server

Terminal 3 – Next.js Frontend:

cd project/aitoearn-web && pnpm run dev

Terminal 4 – (Optional) Electron Client:

cd project/aitoearn-electron && npm run dev

Once all services are running, open your browser to http://localhost:3000 (or the port indicated by the frontend dev server) to access the AiToEarn UI. All API requests will route through your local aitoearn-server instance running on port 3000.

Summary

• AiToEarn uses an Nx + pnpm monorepo structure with separate workspaces for the backend (project/aitoearn-backend) and frontend (project/aitoearn-web).
• Backend setup requires copying config.js to local.config.js in both aitoearn-ai and aitoearn-server apps to override default settings for local development.
• Nx CLI commands like pnpm nx serve aitoearn-ai handle the build and serve process for individual applications.
• Docker Compose at the repository root provides MongoDB and Redis services required for data persistence.
• Frontend configuration relies on environment variables in .env.local to point to the local API server at http://localhost:3000.

Frequently Asked Questions

What Node.js version is required for AiToEarn?

AiToEarn requires Node.js 20.18.x or higher, as enforced by the engine requirements in project/aitoearn-backend/package.json and indicated by the project's README badges. Using an older version may result in dependency installation errors or runtime failures with native modules.

How do I configure local database connections?

Edit the local.config.js files created from config.js in both apps/aitoearn-ai/config/ and apps/aitoearn-server/config/. Update the MONGODB_URI to mongodb://localhost:27017/aitoearn and REDIS_URL to redis://localhost:6379 if running Docker on the host network, or use the service names (mongo, redis) if running the backend inside Docker containers.

Can I run AiToEarn without Docker?

Yes, but you must provide your own MongoDB and Redis instances. Install MongoDB Community Edition and Redis locally, then update the local.config.js files in both backend applications to point to your local instances (typically localhost:27017 and localhost:6379). The Docker setup is recommended for consistency but is not strictly required.

What is the difference between aitoearn-ai and aitoearn-server?

aitoearn-ai is the AI Agent service that handles large language model interactions, content generation, and automated trading logic, running on port 3001 by default. aitoearn-server is the unified API gateway that provides HTTP endpoints, OAuth relays, and SSE/MCP protocols for the frontend, running on port 3000. The frontend communicates exclusively with aitoearn-server, which in turn delegates AI tasks to aitoearn-ai via internal HTTP calls.

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