Developer Guide

This guide covers developing OASM from source: cloning the monorepo, initializing the environment, running the Console, Core API, and workers locally, managing database migrations, and the environment variables each service expects. For a production deployment, see Deployment.

Prerequisites

Before you begin, ensure you have the following installed:

Task (taskfile) — Installation Guide
Node.js v22+ — Installation Guide
Go 1.26+ — Installation Guide
PostgreSQL v17+ (with pgvector extension)
Docker & Docker Compose (recommended for database and full stack)

Clone the repository

git clone https://github.com/oasm-platform/open-asm.git
cd open-asm

The repository is a monorepo with pnpm workspaces combining the Node-based services — console and core-api — alongside the Go worker.

Project Structure

open-asm/
├── core-api/           # NestJS API server
│   ├── src/            # Source code
│   ├── example.env     # Environment template
│   └── package.json
├── console/            # React web interface
│   ├── src/            # React components
│   ├── public/         # Static assets
│   └── package.json
├── worker/             # Go-based scanning workers
│   ├── cmd/            # CLI and App entry points
│   ├── internal/       # Business logic
│   ├── scripts/        # Install scripts (install.ps1, install.sh)
│   ├── go.mod          # Go module definition
│   └── .example.env    # Environment template
├── grpc-client/        # Generated gRPC stubs (Go + TypeScript)
├── .open-api/          # Auto-generated API docs
├── docker-compose.yml  # Container orchestration
├── taskfile.yml        # Task automation
└── README.md           # Documentation

console/ — React 19 + TanStack Router + Vite.
core-api/ — NestJS 11 (REST on port 6276, gRPC on port 16276).
worker/ — Go scanning workers (CLI and app entry points).

Initialize Developer Environment

To set up your local development environment, run the following command:

task init

This command will:

Copy example environment files (.env) for core-api, console, and worker
Install project dependencies using npm (managed by the task for each workspace)
Install Go dependencies for the worker
Install worker security tools (nuclei, subfinder, httpx, naabu, dnsx) into worker/oasm-tools/

After running task init, you can start all services using task dev or run them individually as described below.

Running Services

All Services with Task

To start the API and Console development servers simultaneously:

task dev

This starts:

Core API at http://localhost:6276
Console at http://localhost:5173 (Vite dev server)

Core API

task api:dev

Or directly:

cd core-api && npm run start:dev

The API runs on port 6276 (base path http://localhost:6276/api) with the gRPC server on port 16276.

Console (Web Interface)

task console:dev

Or directly:

cd console && npm run dev

Workers

To run workers locally in CLI mode:

task worker:dev

With custom parameters:

task worker:dev replicas=3 maxJobs=10 apiKey=<your-api-key> network=<target-network>

To run workers in app mode (env-driven):

task worker:dev-app

See Worker for the environment variables workers consume.

Database Setup

task init does not automatically start PostgreSQL. You can either:

Use Docker Compose to start PostgreSQL and Redis (both are required for local development):
docker compose up postgres redis -d
Use your own PostgreSQL instance and update core-api/.env accordingly.

The database uses PostgreSQL 17 with the pgvector extension for vector operations. For the full stack (including workers, geo-ip, and rustfs), run task docker-compose instead — see Using Docker Compose.

Database Migration

Database migrations are managed using TypeORM. The migration scripts are defined in core-api/taskfile.yml and can be executed using the task commands.

Run All Pending Migrations

This command executes all pending database migrations:

task migration:run

This will:

Connect to the PostgreSQL database
Check for pending migrations in the migrations table
Run all new migrations that haven’t been applied yet

Generate a New Migration

To generate a new migration with a custom name:

task migration:generate MIGRATION_NAME=YourMigrationName

For example:

task migration:generate MIGRATION_NAME=AddUserTable

This will create a new migration file in core-api/src/database/migrations/.

Revert the Last Migration

To rollback the most recently executed migration:

task migration:revert

Note: This will only revert one migration at a time. Repeat if needed.

Migration with Docker Compose

If you prefer to run migrations using Docker (useful when not running PostgreSQL locally):

docker compose up migration

This starts the PostgreSQL container (if not running), runs the migration service, applies all pending migrations, removes the migration container, and starts core-api once migrations complete. To keep the container for debugging:

docker compose run --rm migration

The --rm flag ensures the container is removed after it stops.

Development Conventions

Code Style

Core API (NestJS): Uses ESLint and Prettier.
task api:lint
Console (React): Uses ESLint and Prettier.
task console:lint
Workers (Go): Uses go fmt and go vet.
task worker:format task worker:lint

Testing

Core API: Uses Jest for testing.

task api:test           # Unit tests
task api:test:one SPEC=path/to/spec.ts   # Run a single test file
cd core-api && npm run test:watch    # Watch mode
cd core-api && npm run test:e2e      # End-to-end tests

Console: Uses Vitest for unit tests and Playwright for e2e tests.

task console:test       # Unit tests
cd console && npm run e2e           # E2E tests

Workers: Uses Go testing.
task worker:test

Build

task api:build      # Build the Core API
task build          # Build all services (API + Console + Worker)

API Client Generation

After making changes to the API contract, regenerate the console API client:

task gen-api

This uses orval to generate TanStack Query hooks from the OpenAPI spec. The source spec lives at .open-api in core-api (the docs site mirrors it at api-reference/openapi.json).

gRPC Stub Generation

After modifying proto files, regenerate gRPC stubs:

task proto

This generates Go and TypeScript stubs into grpc-client/.

Environment variables

Each service reads its configuration from its own .env file, copied from the example templates by task init. The table below lists the variables used in local development with their defaults.

Never commit .env files — they are gitignored. The worker’s WORKER_API_KEY must match the workspace key the Core API expects; a mismatch prevents workers from registering, see Worker.

Using Docker Compose

To run the entire stack using Docker Compose:

task docker-compose

This starts:

Console (port 3000)
Core API (port 6276, gRPC port 16276)
3 Worker instances
PostgreSQL with pgvector (port 5432)
Redis (port 6379)
Geo-IP proxy (port 4360)
Rustfs S3 storage (port 9000)

Local CI Testing

Before pushing changes, you can run GitHub Actions workflows locally using act to catch issues early.

Prerequisites

Docker Desktop must be installed and running

Install act:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash

# Windows (Git Bash)
curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash

Usage

# List available workflows
bash .github/scripts/test-local.sh

# Run a specific workflow
bash .github/scripts/test-local.sh check-lint
bash .github/scripts/test-local.sh worker-ci

# Validate all workflows (dry-run)
bash .github/scripts/test-local.sh --all

# Custom act binary path
ACT_BIN=act bash .github/scripts/test-local.sh check-lint

Local Test Equivalents

CI Workflow	Local Command
`check-lint.yml`	`task lint`
`check-test.yml`	`task api:test`
`check-build.yml`	`task build` (requires Docker)
`frontend-tests.yml`	`cd console && npm run test:run`
`worker-ci.yml`	`task worker:lint && task worker:check`

Notes

Workflows using docker/build-push-action with multi-platform builds (build-release.yml, build-nightly.yml) need QEMU and native CI runners — they cannot run locally.
dorny/paths-filter may not detect file changes correctly in shallow clones. Use --full-history or test specific jobs.
Docker layer caching (type=gha) is not available locally, but builds will still work.

Contributing

We welcome contributions! Please follow these steps:

Fork the repository.
Create a feature branch: git checkout -b feature/amazing-feature.
Make your changes and commit them following Conventional Commits:
git commit -m 'feat(scope): add amazing feature'
Test CI workflows locally: bash .github/scripts/test-local.sh <workflow>
Push to the branch: git push origin feature/amazing-feature.
Open a Pull Request.

Please ensure your code adheres to the project’s coding standards and passes all tests before submitting a PR.

​Prerequisites

​Clone the repository

​Project Structure

​Initialize Developer Environment

​Running Services

​All Services with Task

​Core API

​Console (Web Interface)

​Workers

​Database Setup

​Database Migration

​Run All Pending Migrations

​Generate a New Migration

​Revert the Last Migration

​Migration with Docker Compose

​Development Conventions

​Code Style

​Testing

​Build

​API Client Generation

​gRPC Stub Generation

​Environment variables

​Using Docker Compose

​Local CI Testing

​Prerequisites

​Usage

​Local Test Equivalents

​Notes

​Contributing

Prerequisites

Clone the repository

Project Structure

Initialize Developer Environment

Running Services

All Services with Task

Core API

Console (Web Interface)

Workers

Database Setup

Database Migration

Run All Pending Migrations

Generate a New Migration

Revert the Last Migration

Migration with Docker Compose

Development Conventions

Code Style

Testing

Build

API Client Generation

gRPC Stub Generation

Environment variables

Using Docker Compose

Local CI Testing

Prerequisites

Usage

Local Test Equivalents

Notes

Contributing