Stigmem Reference Node

Single-host reference implementation of the Stigmem protocol. The modular protocol specs live under ../spec/specs/, with the generated protocol composition at ../spec/PROTOCOL.md.

Quick start

# install
pip install .

# run (auth disabled, local db)
stigmem-node

# run with auth
STIGMEM_AUTH_REQUIRED=true STIGMEM_DB_PATH=./data/stigmem.db stigmem-node

Default port: 8765. Override with STIGMEM_PORT.

Configuration

All settings via environment variables (prefix STIGMEM_):

CORS

The Stigmem node ships with CORS disabled by default. Enable it only for the deployment shape you operate.

Local development (any localhost port)

STIGMEM_CORS_DEV_LOCALHOST=1

Accepts any Origin matching ^https?://(localhost|127\.0\.0\.1)(:\d+)?$. Use this when the UI and API run on separate, dynamically chosen localhost ports.

Production with a known UI origin

STIGMEM_CORS_ALLOWED_ORIGINS=https://stigmem-ui.example.com

Production with multiple UI origins

STIGMEM_CORS_ALLOWED_ORIGINS=https://a.example.com,https://b.example.com

Self-managed regex (advanced)

STIGMEM_CORS_ALLOWED_ORIGIN_REGEX=^https://[a-z0-9-]+\.example\.com$

Credentials

STIGMEM_CORS_ALLOW_CREDENTIALS defaults to true and controls whether browsers may send cookies or Authorization headers cross-origin. Set it to false only when the deployment does not use credentialed browser requests.

Security note

Do not combine STIGMEM_CORS_DEV_LOCALHOST=1 with a production deployment. The dev-localhost regex is intentionally permissive and must only run on maintainer-controlled machines.

API

Running tests

cd stigmem/node
pip install ".[dev]"
pytest

Docker

docker build -t stigmem-node .
docker run -p 8765:8765 -v $(pwd)/data:/data stigmem-node