Installation

Install MeshOptixIQ using the official Docker image (recommended for all deployments).

docker run -p 8000:8000 \
  -e MESHOPTIXIQ_DEMO_MODE=true \
  -e API_KEY=demo \
  -e GRAPH_BACKEND=inmemory \
  meshoptixiq/meshoptixiq:latest
# Open http://localhost:8000  (auto-login with API key: demo)

Prerequisites

• Docker — required for the container installation
• Neo4j or PostgreSQL — optional when using demo mode or the InMemory backend
• sFlow listener (UDP/6343): optional; required for Flow Analytics (Enterprise). Enable with SFLOW_ENABLED=true.

Docker Installation

The easiest way to run MeshOptixIQ is via our official Docker image.

docker pull meshoptixiq/meshoptixiq:latest

Run with Docker

docker run -d \
  -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_PASSWORD="your-password" \
  -v $(pwd)/configs:/app/configs \
  meshoptixiq/meshoptixiq:latest
# Open http://localhost:8000
# API_KEY behavior:
#   Demo mode  — defaults to "demo" (set automatically by the lifespan handler if omitted)
#   Production — recommended; without it, the server starts in open-access mode (all requests admitted)
# Note: all endpoints require the X-API-Key header even in demo mode — 401 is returned if missing

Quickstart with Docker Compose

For a three-service stack (API + Neo4j + Redis), use the included compose file:

cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  neo4j:
    image: neo4j:5.15
    environment:
      NEO4J_AUTH: neo4j/changeme
    ports: ["7687:7687"]
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]
  meshoptixiq:
    image: meshoptixiq/meshoptixiq:latest
    environment:
      NEO4J_URI: bolt://neo4j:7687
      NEO4J_PASSWORD: changeme
      REDIS_URL: redis://redis:6379
      API_KEY: changeme
      MESHOPTIXIQ_LICENSE_KEY: ${MESHOPTIXIQ_LICENSE_KEY}
    ports: ["8000:8000"]
    depends_on: [neo4j, redis]
EOF
docker compose up -d

docker pull meshoptixiq/meshoptixiq:enterprise-latest

License Activation

The license key is set only on the API server. The CLI (meshq) and MCP server read the plan from the local API via MESHOPTIXIQ_API_URL — they do not need the key themselves.

Obtaining a License

Purchase a license at: https://meshoptixiq.com/pricing

Method 1: Environment Variable (Docker — API server)

Set the license key on the API server container. The CLI does not need it.

export MESHOPTIXIQ_LICENSE_KEY="mq-prod-xxxxxxxxxx"

# API server (needs the key)
docker run -e MESHOPTIXIQ_LICENSE_KEY \
  -e API_KEY="changeme" \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_PASSWORD="your-password" \
  -p 8000:8000 \
  meshoptixiq/meshoptixiq:latest

# CLI (points to the API server — no license key needed)
docker run -e MESHOPTIXIQ_API_URL="http://host.docker.internal:8000" \
  meshoptixiq/meshoptixiq:latest meshq ingest --source /app/configs/inventory.yaml

Method 2: License File (Persistent — API server host)

Recommended for VM or bare-metal API server installations:

# On the API server host
mkdir -p ~/.meshoptixiq
echo "mq-prod-xxxxxxxxxx" > ~/.meshoptixiq/license.key
chmod 600 ~/.meshoptixiq/license.key

Verification

After activating your license on the API server, verify it is active:

# Via CLI (delegates to API)
meshq license

# Direct API query (requires X-API-Key header; protected by default)
curl -H "X-API-Key: $API_KEY" http://localhost:8000/health/license
# {"plan":"pro","expires":"2027-12-31","days_remaining":310,"demo_mode":false}

# To make /health/license unauthenticated (e.g. for k8s probes), set:
# MESHQ_PROTECT_HEALTH=false

Troubleshooting

If you encounter license-related issues, see the Troubleshooting Guide for solutions to:

• Cannot reach local API (CLI/MCP)
• License expired (API server)
• Device limit exceeded
• Grace period activation