# Quickstart (/deploy/quickstart)



<JsonLdHowTo
  name="Run KubeMQ and send your first message"
  step="[
  {
    name: &#x22;Get your key&#x22;,
    text: &#x22;Create a free KubeMQ account and copy the license token a standalone server needs to start.&#x22;,
  },
  {
    name: &#x22;Run KubeMQ&#x22;,
    text: &#x22;Start KubeMQ with a single Docker command that opens gRPC on port 50000, REST on port 9090, and the web dashboard on port 8080.&#x22;,
  },
  {
    name: &#x22;Open the dashboard&#x22;,
    text: &#x22;Open http://localhost:8080 to confirm the server is running before sending any messages.&#x22;,
  },
  {
    name: &#x22;Send & receive via Queues&#x22;,
    text: &#x22;Send a message to a queue channel called orders and receive it back, watching the channel tick in the dashboard.&#x22;,
  },
]"
/>

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 [#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 →](/deploy/license-key)

## 2 · Run KubeMQ [#2--run-kubemq]

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

<RunKubeMQ />

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

## 3 · Open the dashboard [#3--open-the-dashboard]

Open [`http://localhost:8080`](http://localhost:8080).

<Callout type="info">
  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.
</Callout>

## 4 · Send & receive your first message [#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.

<Tabs items="[&#x22;kmq CLI&#x22;, &#x22;cURL&#x22;, &#x22;SDK&#x22;]">
  <Tab value="kmq CLI">
    Install `kmq`, KubeMQ's command-line client, then send and receive:

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

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

    <Callout type="tip" title="Expected output">
      ```text
      {"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.
    </Callout>

    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](/deploy/cli).
  </Tab>

  <Tab value="cURL">
    No installation needed — this talks straight to the REST gateway on port `9090`.

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

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

    <Callout type="tip" title="Expected output">
      ```text
      {"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}`.
    </Callout>
  </Tab>

  <Tab value="SDK">
    ```go title="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](/sdks).
  </Tab>
</Tabs>

## 5 · Pick your path [#5--pick-your-path]

<Cards>
  <Card title="Replace your messaging stack" href="/deploy/scenarios/replace" description="Point your existing Kafka, RabbitMQ, SQS/SNS, MQTT, or other client at KubeMQ by changing one connection string." />

  <Card title="Build on the AI-agent fabric" href="/deploy/scenarios/agents" description="Connect an MCP host, register an agent, or drive KubeMQ from an LLM." />

  <Card title="Explore messaging patterns" href="/learn" description="Events, Events Store, Queues, and RPC (Commands & Queries) in depth." />

  <Card title="Drive from the terminal" href="/deploy/cli" description="Install kmq, connect, and teach your coding agent to drive KubeMQ." />

  <Card title="Deploy to production" href="/deploy/kubernetes-helm" description="Install KubeMQ on Kubernetes with Helm, HA, and a production checklist." />
</Cards>

## Didn't work? [#didnt-work]

<Callout type="warn">
  * **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](/deploy/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.
</Callout>