Skip to main content
This guide takes you from nothing to ingesting telemetry and running a query that ties logs to traces to host metrics — all on your own machine.

​
Prerequisites

  • Docker and Docker Compose (the sandbox brings up Postgres + MinIO + MoleSignal).
  • About 2 GB of free RAM for the standalone profile.

​
Run the sandbox

1

Clone and start

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

# 1-command sandbox: Postgres + MinIO + MoleSignal standalone
docker compose -f deploy/docker/docker-compose.yaml --profile standalone up
Once it’s up:
2

Log in and get a token

Authenticate to obtain a JWT and your org_id:
curl -X POST http://localhost:5080/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"[email protected]","password":"admin"}'
The response contains the JWT and your org_id. Export them for the next steps:
export MS_JWT="<jwt-from-response>"
export MS_ORG="<org_id-from-response>"
3

Send your first data

Native HTTP JSON ingest works with curl, an app SDK, Vector, or Fluent Bit out of the box. Timestamps are microseconds since the Unix epoch.
curl -X POST http://localhost:5080/api/v1/ingest/logs/app \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '[{"_timestamp":1700000000000000,"level":"error","msg":"db pool exhausted","trace_id":"abc123"}]'
4

Query — and watch the signals connect

The same trace_id ties logs to traces and to host metrics, because they share one store:
curl -X POST http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d "{\"org_id\":\"$MS_ORG\",\"language\":\"sql\",
       \"statement\":\"SELECT * FROM app WHERE trace_id = 'abc123'\",
       \"time_range\":{\"start\":0,\"end\":2000000000000000},
       \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"
The result includes rows, columns, scanned_rows, took_ms, and cache_hit.

​
Next steps

Ingest from your stack

Point OpenTelemetry, Prometheus, Loki, or Filebeat at MoleSignal with no rewrite.

Cross-signal correlation

The killer feature: jump between signals without copy-pasting trace IDs.

Deploy for real

Move from the sandbox to a multi-role or Kubernetes deployment.

Configuration

TOML config and MS_* environment overrides.