The whole flow takes about 5 minutes the first time — roughly 2-3 of those are the free account signup in Step 1. By the end you'll have KubeMQ running, the dashboard open, and a message you sent yourself showing up in real time.

1 · Get your key

A standalone KubeMQ server needs a free license token to start — there's no keyless mode. Grabbing one is under a minute if you already have an account, ~2-3 minutes including the free signup if you don't.

Get a license key →

2 · Run KubeMQ

Replace YOUR_LICENSE_KEY below with the token from Step 1, then run:

docker run -d \  --name kubemq \  -p 50000:50000 \  -p 9090:9090 \  -p 8080:8080 \  -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY \  europe-docker.pkg.dev/kubemq/images/kubemq:next

This starts the broker with gRPC on port 50000, REST on port 9090, and the web dashboard on port 8080.

3 · Open the dashboard

Open http://localhost:8080.

An empty dashboard here is healthy — it just means nothing has been sent yet. The orders channel appears and ticks the moment you complete Step 4.

4 · Send & receive your first message

This uses Queues — guaranteed, persistent delivery where send and receive are independent steps, so nothing is lost if you run them in either order. Send one message to a channel called orders, then receive it back.

Install kmq, KubeMQ's command-line client, then send and receive:

curl -sSfL https://raw.githubusercontent.com/kubemq-io/kmq/main/install.sh | sh

kmq context create default --api-address http://localhost:8080
kmq queue send orders '{"id":1}'
kmq queue receive orders

Expected output

{"id":1}

kmq queue receive orders prints the body of the message it just pulled off the orders channel — the same {"id":1} you sent.

Watch the orders channel tick in the dashboard as the two commands run. The full command reference and the agent-skill install are in Drive KubeMQ from the terminal.

No installation needed — this talks straight to the REST gateway on port 9090.

Terminal

curl -X POST http://localhost:9090/queue/send \
  -H "Content-Type: application/json" \
  -d '{
    "Channel": "orders",
    "ClientID": "quickstart-curl",
    "BodyString": "{\"id\":1}"
  }'

Terminal

curl -X POST http://localhost:9090/queue/receive \
  -H "Content-Type: application/json" \
  -d '{
    "Channel": "orders",
    "ClientID": "quickstart-curl",
    "MaxNumberOfMessages": 1,
    "WaitTimeSeconds": 5
  }'

Expected output

{"is_error":false,"message":"OK","data":{"MessagesReceived":1,"Messages":[{"MessageID":"...","Channel":"orders","Body":"eyJpZCI6MX0="}]}}

Body comes back base64-encoded (the wire format for raw bytes) — decode it and you'll see {"id":1}.

main.go

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/kubemq-io/kubemq-go/v2"
)

func main() {
    ctx := context.Background()
    client, err := kubemq.NewClient(ctx,
        kubemq.WithAddress("localhost", 50000),
        kubemq.WithClientId("quickstart"),
    )
    if err != nil {
        log.Fatal("Failed to create client:", err)
    }
    defer client.Close()

    channel := "orders"

    // Send
    result, err := client.SendQueueMessage(ctx, kubemq.NewQueueMessage().
        SetChannel(channel).
        SetBody([]byte(`{"id":1}`)),
    )
    if err != nil {
        log.Fatal("Failed to send:", err)
    }
    if result.IsError {
        log.Fatal("Send error:", result.Error)
    }
    fmt.Printf("Sent: id=%s\n", result.MessageID)

    // Receive
    resp, err := client.PollQueue(ctx, &kubemq.PollRequest{
        Channel:            channel,
        MaxItems:           1,
        WaitTimeoutSeconds: 5,
        AutoAck:            true,
    })
    if err != nil {
        log.Fatal("Failed to receive:", err)
    }
    for _, dsMsg := range resp.Messages {
        fmt.Printf("Received: %s\n", dsMsg.Message.Body)
    }
}

Requires Go 1.23 or later. Nine more languages plus REST are covered in Client SDKs.

Port already in use — something else is bound to 50000, 9090, or 8080. Stop it, or change the published ports in the docker run command.
Missing or invalid token — KUBEMQ_TOKEN must be a real key from Get a license key. A missing or malformed token makes the server exit immediately on startup.
Container not Up — run docker ps and check the kubemq container's status; docker logs kubemq shows the exit reason if it isn't running.

Quickstart

1 · Get your key

2 · Run KubeMQ

3 · Open the dashboard

4 · Send & receive your first message

5 · Pick your path

Replace your messaging stack

Build on the AI-agent fabric

Explore messaging patterns

Drive from the terminal

Deploy to production

Didn't work?

On this page