Installation

5 min readFor first-time operatorsUpdated 2026-05-19

What you'll do

Get a local Stigmem node running. Three paths: a two-node federated quickstart with Docker Compose (fastest), running from the Python source directly (development), or installing as a persistent macOS LaunchAgent (always-on local node).

Local-dev defaults only.

The Docker Compose path runs plaintext federation between two loopback containers for the quickstart. Production federation requires mTLS — see mTLS federation transport before exposing a node outside of localhost.

Prerequisites

Tool

Minimum version

Notes

Docker

≥ 24

The fastest path — pre-built image and Compose definitions.

Docker Compose (v2)

≥ 2.20

Used by the quickstart and the 4-node soak topology.

Python (alt. path)

≥ 3.11

Only needed for the source-tree development path or the macOS LaunchAgent.

Path A · Single-command install (two-node federation)

git clone https://github.com/eidetic-labs/stigmem
cd stigmem
docker compose up --build -d

This builds the reference node image once and starts two federated nodes:

Container	Host port	Well-known URL
node-a	8765	http://localhost:8765/.well-known/stigmem
node-b	8766	http://localhost:8766/.well-known/stigmem

Verify both are healthy:

curl -s http://localhost:8765/healthz   # {"status":"ok"}
curl -s http://localhost:8766/healthz   # {"status":"ok"}

For the full two-node federation walk-through — peer handshake, fact assertion, replication verification — continue to the Quickstart.

Docker Compose configuration

docker-compose.yml in the repo root sets up the two-node quickstart cluster. Key environment variables:

Variable

Default

Description

STIGMEM_FEDERATION_ENABLED

true

Enable / disable federation pull loop.

STIGMEM_NODE_URL

(container URL)

Public URL of this node — used in PeerDeclarations.

STIGMEM_FEDERATION_INSECURE

1

Local quickstart-only plaintext federation acknowledgement.

STIGMEM_LOCAL_DEV_ALLOW_INSECURE_NON_LOOPBACK

1

Allows local Docker service DNS names (node-a, node-b) for the plaintext demo.

STIGMEM_FEDERATION_PULL_INTERVAL_S

30

Seconds between pull cycles.

STIGMEM_SECRET_KEY

auto-generated

Ed25519 private key seed — persist this across restarts.

To customize, copy docker-compose.yml and edit the environment: block before running.

Production checklist.

Remove both insecure local-dev flags (STIGMEM_FEDERATION_INSECURE and STIGMEM_LOCAL_DEV_ALLOW_INSECURE_NON_LOOPBACK) and configure mTLS per mTLS federation transport before peering outside localhost.

4-node topology (soak / staging)

For multi-node deployments, use the soak Compose file:

docker compose -f infra/docker-compose.soak.yml up --build -d

This starts four nodes (node-a through node-d on ports 8765–8768) in a full-mesh topology. See the 4-node topology guide for peer wiring, failure injection, and soak metrics.

Path B · Running without Docker (development)

For development against the source directly:

cd stigmem/node
pip install -e .      # or: uv sync
python -m stigmem_node

The node starts on http://localhost:8000. Interactive Swagger UI at http://localhost:8000/docs.

Running as a persistent service (macOS)

The service-install.sh script registers Stigmem as a macOS LaunchAgent that starts automatically at login and restarts on crash — no Docker required.

Prerequisites

A Python venv built in the repo root (run uv sync if you haven't already):

uv sync

The script expects .venv/bin/stigmem-node to exist; it will fail fast if it doesn't.

Install

bash scripts/service-install.sh

The script:

1. Generates a LaunchAgent plist at ~/Library/LaunchAgents/com.eidetic-labs.stigmem.plist.
2. Bootstraps it with launchctl bootstrap (no sudo required).
3. Polls http://127.0.0.1:8765/healthz for up to 10 seconds and prints the result.

The service runs with these environment variables baked in:

Variable

Value

Notes

STIGMEM_HOST

127.0.0.1

Localhost-only bind.

STIGMEM_PORT

8765

Default port.

STIGMEM_DB_PATH

data/stigmem.db

Relative to the repo root.

STIGMEM_FEDERATION_ENABLED

false

Standalone node only — no federation peering by default.

Logs are written to logs/stigmem.log (stdout) and logs/stigmem-error.log (stderr).

Verify

curl -s http://127.0.0.1:8765/healthz   # {"status":"ok"}
lsof -i :8765                           # shows the stigmem-node process

Uninstall

bash scripts/service-uninstall.sh

Stops the service, unregisters it from launchctl, and removes the plist. The database at data/stigmem.db is preserved.

note

The service label is com.eidetic-labs.stigmem. To inspect it directly:

launchctl print gui/$(id -u)/com.eidetic-labs.stigmem

Upgrading

git pull
docker compose up --build -d   # rebuilds the image from updated source

Data volumes persist across rebuilds. Run database migrations automatically on startup — there is no manual migration step.

Teardown

docker compose down      # stop containers; preserve data volumes
docker compose down -v   # stop and delete all data volumes

What's next

Step 2Quickstart tutorialAssert your first fact, query it back, watch a conflict open.Step 3SDK quickstartConnect from Python, TypeScript, or Go.ReadmTLS federation transportWhat changes when you leave the local-dev defaults.