Quickstart

This guide starts a local MoleSignal sandbox, sends one log event, and finds the event in the web UI and through the query API. The sandbox is for evaluation only.

Prerequisites

Docker with Docker Compose v2.
About 2 GB of free memory.
Free local ports: 5080 (web UI and API), 5082, 5432 (PostgreSQL), 9000 and 9001 (RustFS).

Start the sandbox

Clone the repository and start the stack

git clone https://github.com/molesignal/molesignal
cd molesignal
docker compose -f deploy/docker/docker-compose.yaml --profile standalone up

The first start downloads or builds the images, which can take several minutes. The stack contains PostgreSQL 17 for metadata, RustFS as S3-compatible object storage, and one MoleSignal process that runs every role and serves the web UI.Check that the server is ready:

curl http://localhost:5080/api/v1/healthz

A healthy server returns {"status":"ok"}.

Open http://localhost:5080 and sign in with:

Email: [email protected]
Password: admin

The sandbox configuration creates this root account on the first start only. Replace the account before any use beyond a local evaluation. See Production checklist.

The RustFS console is available at http://localhost:9001 with rustfsadmin / rustfsadmin. These sandbox credentials are not secure.

Get an access token

The API accepts a bearer token. Sign in through the API to get a login token (valid for 24 hours by default) and the organization id:

RESP=$(curl -s -X POST http://localhost:5080/api/v1/auth/signin \
  -H 'content-type: application/json' \
  -d '{"email":"[email protected]","password":"admin"}')

export MS_JWT=$(echo "$RESP" | jq -r .token)
export MS_ORG=$(echo "$RESP" | jq -r .org_id)

Without jq, copy token and org_id from the response and export them manually.

Use an API token or an intake token for senders that run longer than the login token lifetime. See Datasource.

Send a log event

Native HTTP JSON intake takes an array of records. _timestamp holds microseconds since the Unix epoch. The stream app is created on the first write.

curl -X POST http://localhost:5080/api/v1/intake/logs/app \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d "[{\"_timestamp\":$(date +%s)000000,\"level\":\"error\",\"msg\":\"db pool exhausted\",\"trace_id\":\"abc123\"}]"

The response reports the accepted records:

{"accepted":1,"rejected":0,"errors":[]}

Find the event in the web UI

Open Logs.
Select the stream app in the stream selector.
Keep the time range at Last 1 hour and select Run.

The result table shows the event. Select the row to inspect its original fields.

Query the event with the API

Run the same lookup through the query API. Always send a bounded time_range in microseconds; a very wide range makes the planner turn the query into an asynchronous search job.

NOW=$(date +%s)000000

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 level, msg, trace_id FROM app WHERE trace_id = 'abc123'\",
       \"time_range\":{\"start\":$((NOW - 3600000000)),\"end\":$((NOW + 60000000))},
       \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"

The response contains columns, rows, scanned_rows, and took_ms:

{"columns":["level","msg","trace_id"],"rows":[["error","db pool exhausted","abc123"]],"scanned_rows":1,"took_ms":120}

Load sample data

A workspace without data shows empty pages. Load a small, correlated demo set (logs, metrics, and traces that share trace_id values) to try cross-signal investigation:

curl -X POST http://localhost:5080/api/v1/onboarding/sample-data \
  -H "authorization: Bearer $MS_JWT"

The request creates the streams sample_app_logs, sample_app_metrics, and sample_app_traces. The same action is available in the web UI: on Home, select Complete setup in the setup banner, then select Load next to Load sample data. The banner disappears after every setup step is complete.

Send OpenTelemetry data

OTLP over HTTP works with any OpenTelemetry SDK or Collector. Point the exporter at the /api base path; the exporter appends /v1/logs, /v1/metrics, and /v1/traces:

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5080/api
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $MS_JWT"
export OTEL_SERVICE_NAME=checkout

Telemetry lands in the stream default of each signal type unless a stream-name header selects another stream. See Datasource and Integration guides for Collector, Vector, Fluent Bit, Prometheus, and SDK setups.

Stop the sandbox

# Stop the containers and keep the data
docker compose -f deploy/docker/docker-compose.yaml --profile standalone down

# Stop the containers and delete all sandbox data
docker compose -f deploy/docker/docker-compose.yaml --profile standalone down -v

Troubleshooting

Symptom	Cause and fix
`healthz` returns `503` with `"status":"degraded"`	A subsystem is unhealthy, for example the object store probe. Read the `reason` field and check the `rustfs` container.
Sign-in returns `401`	The root account is created only on the first start. A database volume from an earlier run keeps the earlier password. Run `down -v` to reset the sandbox.
The query returns `202` with a `job_id`	The time range is too wide (about 13.9 hours or more with the defaults), so the planner started an asynchronous search job. Narrow the range, send `Prefer: respond-sync`, or poll `GET /api/v1/query/jobs/{id}`. See Query.
The query returns `422 missing field org_id` or `400 query.stream hint is required`	Send both `org_id` and the `stream` object.
A port is already in use	Stop the other process, or change the published ports in `deploy/docker/docker-compose.yaml`.
OTLP gRPC on `4317` is unreachable from the host	The sandbox Compose file does not publish `4317`. Add a `4317:4317` port mapping to the `molesignal` service.

Next steps

Connect real data

Use the Datasource page, intake tokens, and compatible protocols.

Integration guides

Configure the OpenTelemetry Collector, Vector, Fluent Bit, Filebeat, and Prometheus.

Core concepts

Learn signals, streams, workspaces, and permissions.

Deploy for real

Move from the sandbox to a production deployment.

Get started

Data

Observe

Query and correlate

Reliability

AI ops

Collaboration

Admin

Deploy & operate

Best practices

Resources

Prerequisites

Start the sandbox

Load sample data

Send OpenTelemetry data

Stop the sandbox

Troubleshooting

Next steps

Connect real data

Integration guides

Core concepts

Deploy for real

​Prerequisites

​Start the sandbox

​Load sample data

​Send OpenTelemetry data

​Stop the sandbox

​Troubleshooting

​Next steps

Connect real data

Integration guides

Core concepts

Deploy for real

Prerequisites

Start the sandbox

Load sample data

Send OpenTelemetry data

Stop the sandbox

Troubleshooting

Next steps