Local Development

Use this path when you want to modify Monkeys code, debug a service, or prepare a contribution.

Recommended Workspace

Keep repositories as siblings:

INFMONKEYS/
  monkeys/
  monkeys-server/
  monkeys-studio/
  monkeys-kernel/
  monkeys-compute/
  ...

Start only the services required for the feature you are changing. You do not need the full ecosystem for every contribution.

Start Shared Infrastructure

cd monkeys/docker/infrastructure
docker compose up -d

This starts PostgreSQL, Redis, Elasticsearch, Conductor, MinIO, Prometheus, and Grafana.

Run The Backend In Dev Mode

cd monkeys-server
yarn install --frozen-lockfile
cp config.yaml.example config.yaml
yarn migration:run
yarn start:dev

Useful backend commands:

Command	Purpose
`yarn start:dev`	Start NestJS with watch mode.
`yarn build`	Compile the backend.
`yarn lint`	Run ESLint with fixes.
`yarn test`	Run unit tests.
`yarn test:e2e`	Run e2e tests.
`yarn migration:create`	Create a TypeORM migration file.
`yarn migration:run`	Run migrations through `migration_script.js`.

When changing database tables, create a migration under src/database/migrations/. Table names created by migrations should use config.server.appId as the prefix.

Run Studio In Dev Mode

cd monkeys-studio
yarn install --frozen-lockfile
cp .env.example .env
yarn dev

Set the backend endpoint in .env:

SERVER_ENDPOINT=http://127.0.0.1:3000
SERVER_PORT=2048

Studio development commands:

Command	Purpose
`yarn dev`	Start Vite dev server.
`yarn build`	Build production assets.
`yarn lint`	Run ESLint with fixes.
`yarn test`	Run Vitest tests.
`yarn preview`	Preview build output.

Run Capability Services

For work in optional services, read that repository's own README and AGENTS.md first. Most capability services own their own example config, Dockerfile, test commands, and build commands.

Start related infrastructure from monkeys/docker/infrastructure, then run the service directly in development mode or through the profile in monkeys/docker/services.

Debugging Checklist

Confirm infrastructure health with docker compose ps.
Confirm the backend can reach PostgreSQL, Redis, Elasticsearch, Conductor, and MinIO.
Confirm Studio .env points to the backend you are running.
Check browser network requests for /api, /v1, and /socket.io proxy behavior.
Keep credentials in local untracked config files or secret stores.