Getting Started

Set up the Gravity monorepo locally, run each service, and verify the stack with the actual commands and configuration from the repository.

Overview

Gravity is a polyglot monorepo with three apps:

apps/web — Remix frontend
apps/api — NestJS API running on Bun
apps/ai-service — FastAPI service managed with uv

This page reflects the current repository state. A few repo files are inconsistent with each other, so the commands below use the paths and runtime behavior that actually exist in the codebase.

Prerequisites

Before you install anything, make sure these tools are available locally.

Required by the repository:

Node.js 18+
pnpm
bun
uv
Python 3.14+

Use these commands to verify your local toolchain:

node -v
pnpm -v
bun -v
uv -v
python -V

Install dependencies

The repository includes a bootstrap script that installs dependencies for all three runtimes.

Clone the repository

git clone <your-repo-url>
cd core

Run the bootstrap script

./scripts/bootstrap.sh

The script does the following:

pnpm install
cd apps/api && bun install
cd apps/ai-service && uv sync

The root README.md mentions pnpm setup, but that script does not exist in the current root package.json. Use ./scripts/bootstrap.sh instead.

Environment variables

There are currently no repository-provided environment example files for local development.

No .env.example file is present
No docker-compose.yml, compose.yml, or compose.yaml file is present
No repo-defined environment variables appear required for the current minimal local setup

That means you can start the project without creating an .env file.

Run the project locally

You can start everything together from the repository root.

Run all services

pnpm dev

This runs turbo run dev --parallel from the root package.json.

Run a single service when needed

Use the app-level dev commands below if you want to work on one service at a time.

pnpm --filter @repo/web dev

Local URLs and ports

The current repository points to these local services:

Web app: check the URL printed by the Remix dev server
API: http://localhost:3001
AI service: http://localhost:8001

The repo currently contains a few port and naming mismatches:

The root README.md and API CORS config expect the frontend on http://localhost:3000
apps/web/README.md says the web app is available at http://localhost:5173
apps/api/src/main.ts exposes the API on port 3001
The root script dev:py points to apps/py-service, but the actual directory is apps/ai-service

Because of this, the safest way to confirm the web URL is to use the address printed in the apps/web dev server output.

Verify everything is working

After the services start, verify each backend service directly.

Check the API health endpoint

curl http://localhost:3001/health

Expected response:

{"status":"ok","service":"api"}

Check the AI service health endpoint

curl http://localhost:8001/health

Expected response:

{"status":"ok"}

Open the web app

Open the local URL printed by the Remix dev server and confirm the starter UI loads.

Repository notes to keep in mind

The current codebase is still scaffold-level, so a few repo details are worth calling out while setting up the project:

apps/ai-service/pyproject.toml requires Python >=3.14
The API route implemented in code is GET /health, not GET /api/health
The repo includes Dockerfiles for each app, but no compose-based local orchestration file
The root README references shared packages/* paths that are not present yet

Next steps

Once the stack is running locally, continue with the rest of the docs:

Introduction

Read the high-level overview of the repository and its current product scope.

Features

Review the currently implemented capabilities across the web, API, and AI service.

Integrations

Explore how the services, tooling, and deployment pieces connect.

Was this page helpful?