User Guide

MIG User Guide

This guide explains how to operate and integrate a MIG v0.1 runtime in development and production-like environments.

If you want the shortest path to first success, start with Quickstart.

1) Runtime scope

The runtime exposes MIG core operation planes:

Discovery: HELLO, DISCOVER
Invocation: INVOKE, CANCEL
Events: PUBLISH, SUBSCRIBE
Control: HEARTBEAT

Transport options:

HTTP (required)
gRPC (optional)
NATS (optional)

2) Run modes

2.1 Open mode

MIGD_AUTH_MODE=none migd

2.2 JWT mode

MIGD_AUTH_MODE=jwt \
MIGD_JWT_HS256_SECRET=<set-a-strong-secret> \
migd

JWT mode expectations:

Authorization: Bearer <token>
tenant_id (or tenant) claim
Optional capability scopes via scope / scopes

3) Core configuration

Variable	Default	Description
`MIGD_ADDR`	`:8080`	HTTP listen address
`MIGD_GRPC_ADDR`	empty	gRPC listen address; empty disables gRPC
`MIGD_AUTH_MODE`	`none`	`none` or `jwt`
`MIGD_JWT_HS256_SECRET`	empty	Required when `MIGD_AUTH_MODE=jwt`
`MIGD_ENABLE_METRICS`	`true`	Enables metrics endpoint
`MIGD_NATS_URL`	empty	Enables NATS connectivity
`MIGD_ENABLE_NATS_BINDING`	`true`	Enables NATS request/reply binding
`MIGD_AUDIT_LOG_PATH`	empty	Enables JSONL audit sink

4) Core API surface

POST /mig/v0.1/hello
POST /mig/v0.1/discover
POST /mig/v0.1/invoke/{capability}
POST /mig/v0.1/publish/{topic}
GET /mig/v0.1/subscribe/{topic} (SSE)
POST /mig/v0.1/cancel/{message_id}
POST /mig/v0.1/heartbeat
GET /mig/v0.1/stream (WebSocket)

5) Common workflows

5.1 HELLO

curl -sS -X POST http://localhost:8080/mig/v0.1/hello \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: acme' \
  -d '{
    "header": {"tenant_id": "acme"},
    "supported_versions": ["0.1"],
    "requested_bindings": ["http"]
  }'

5.2 DISCOVER

curl -sS -X POST http://localhost:8080/mig/v0.1/discover \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: acme' \
  -d '{"header": {"tenant_id": "acme"}}'

5.3 INVOKE

curl -sS -X POST http://localhost:8080/mig/v0.1/invoke/observatory.models.infer \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: acme' \
  -d '{
    "header": {
      "tenant_id": "acme",
      "idempotency_key": "idem-1",
      "deadline_ms": 30000
    },
    "payload": {"input": "hello"}
  }'

Behavior notes:

idempotency_key supports safe retries.
deadline_ms limits execution time.
In JWT mode, invocation can be scope-filtered.

5.4 CANCEL

curl -sS -X POST http://localhost:8080/mig/v0.1/cancel/msg-123 \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: acme' \
  -d '{
    "header": {"tenant_id": "acme"},
    "target_message_id": "msg-123",
    "reason": "operator cancel"
  }'

Subscriber:

curl -N http://localhost:8080/mig/v0.1/subscribe/observatory.inference.completed \
  -H 'X-Tenant-ID: acme'

Publisher:

curl -sS -X POST http://localhost:8080/mig/v0.1/publish/observatory.inference.completed \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: acme' \
  -d '{
    "header": {"tenant_id": "acme"},
    "payload": {"status": "ok"}
  }'

6) Optional bindings

6.1 gRPC

MIGD_GRPC_ADDR=:9090 migd

See gRPC Binding.

6.2 NATS

MIGD_NATS_URL=nats://localhost:4222 \
MIGD_ENABLE_NATS_BINDING=true \
migd

See NATS Binding.

7) Operational endpoints

GET /metrics for Prometheus scraping
GET /admin/v0.1/health/conformance for runtime conformance health
GET /ui for browser-based quick checks