Local Development

This guide walks through everything needed to run the opensecstack ecosystem on your local machine — cloning the repo, starting the full stack or a single platform with hot-reload, working without Docker, and configuring your editor for Go, Rust, TypeScript, and Python.

Prerequisites

Install the following tools before cloning the repo. For full environment requirements and alternative install paths see Installation.

Cloning the repo

git clone https://github.com/opensecstack/opensecstack
cd opensecstack

The repository is a monorepo. Each of the 11 platforms lives in its own top-level directory (apiguard/, nis2compass/, etc.). Shared SDK contracts are in sdk/, CITADEL governance in .citadel/, and the ecosystem website in website/. For a map of how all components relate, see the Architecture overview.

Full-stack hot-reload workflow

The dev Docker Compose file mounts source directories as volumes so that most code changes are picked up without rebuilding the container image.

"cm"># From the repo root — starts all services
make dev

"cm"># Verify the API is up
curl http://localhost:8080/api/v1/health
"cm"># → {"status":"ok"}

"cm"># Open the dashboard
"cm"># http://localhost:3000

Hot-reload behaviour per language:

The full stack starts: APIGuard API on port 8080, Dashboard on port 3000, PostgreSQL on 5432, and Redis on 6379.

Running a single platform

You do not need to start the entire stack to work on one platform. Each platform directory contains its own Makefile and .env.example.

"cm"># Example: APIGuard only
cd apiguard
cp .env.example .env   "cm"># Edit with your values
make dev

Replace apiguard with the directory name of the platform you are working on (e.g. nis2compass, threatflow, opencsirt).

Running without Docker

If you prefer to run services directly on the host, start PostgreSQL and Redis first (or run only those two containers), then launch each component individually.

"cm"># 1. Start PostgreSQL and Redis via Docker (or use local installs)
docker run -d --name pg -p 5432:5432 \
  -e POSTGRES_USER=opensecstack \
  -e POSTGRES_PASSWORD=changeme \
  -e POSTGRES_DB=opensecstack \
  postgres:16-alpine

docker run -d --name redis -p 6379:6379 redis:7-alpine

"cm"># 2. Run database migrations
cd apiguard && make migrate

"cm"># 3. Start the Go API server
cd apiguard && go run ./cmd/

"cm"># 4. Start the React dashboard (separate terminal)
cd apiguard/web && npm install && npm run dev

"cm"># 5. Build Rust components
cd apiguard/rust && cargo build --release

Environment variables

Copy .env.example to .env in the platform directory. The following variables are required for APIGuard; every platform has its own set documented in platform/docs/configuration.md.

Common dev tasks

"cm"># Run all tests
make test

"cm"># Run linters
make lint

"cm"># Format code
make fmt

"cm"># Run a sample scan against VAmPI (APIGuard)
cd apiguard && make scan-example

"cm"># Start test targets (VAmPI, crAPI)
cd apiguard && docker compose -f docker-compose.test.yml up -d

IDE setup

VS Code (recommended)

The fastest path is the built-in Dev Container: open the opensecstack/ folder in VS Code and click "Reopen in Container" when prompted. All tools are pre-installed.

For a manual setup, install these extensions:

Recommended .vscode/settings.json:

{
  "go.lintTool": "golangci-lint",
  "go.lintFlags": ["--fast"],
  "rust-analyzer.check.command": "clippy",
  "rust-analyzer.cargo.features": "all",
  "[go]": { "editor.defaultFormatter": "golang.go" },
  "[rust]": { "editor.defaultFormatter": "rust-lang.rust-analyzer" },
  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[typescriptreact]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[python]": { "editor.defaultFormatter": "ms-python.python" }
}

JetBrains (GoLand / RustRover)

• GoLand: open apiguard/ as a Go project, install the Rust plugin, enable golangci-lint under Settings → Go → Linters.
• RustRover: open apiguard/rust/ as a Rust project, install the Go plugin, enable Clippy on save under Settings → Languages & Frameworks → Rust.
• Both IDEs: enable "Format on save", connect the Database tool to localhost:5432 with credentials from .env, and connect Docker integration to the local daemon.

Troubleshooting