In about five minutes you start a KubeMQ server on your machine, create its administrator, send a message and read it back. The server runs a 14-day evaluation that needs no signup. Time: about 5 minutes.

Starting the evaluation accepts the evaluation terms and sends usage data to KubeMQ, as Data sent to KubeMQ describes.

Before you start

Docker Desktop or Docker Engine, running. Podman works too; see Requirements and supported setups. On Windows, use Docker Desktop; only the Docker tab's commands need WSL.
Ports 50000, 9090, 8080 and 9092 free on this machine, and 5672 for the kmq tab.
Outbound HTTPS to license.kubemq.io, directly or through a proxy; see Requirements and supported setups.
On Apple silicon or another Arm machine, the Docker tab needs x86-64 emulation in Docker.

Run KubeMQ

Install kmq

kmq is the KubeMQ command-line tool. On macOS and Linux, download the installer:

curl -fsSL https://raw.githubusercontent.com/kubemq-io/kmq/main/install.sh -o install-kmq.sh

Run it:

sh install-kmq.sh

Check that kmq runs:

kmq version

You should see:

Output

{
  "version": "..."
}

If the installer notes that its folder is not in your PATH, run the export PATH line it prints, then kmq version again.

On Windows, in PowerShell:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/kubemq-io/kmq/main/install.ps1 -OutFile install-kmq.ps1

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

& .\install-kmq.ps1

kmq version

The second command allows the downloaded script in this window only.

Start a server

kmq onboard --goal evaluation --name kubemq --pull --deadline 10m

You should see:

Output

{
  "installation_id": "...",
  "state": "runtime_started_needs_management_setup",
  "target": "docker",
  "resource_id": "...",
  "data_retained": true,
  "next_action": "complete_management_authentication_then_verify"
}

This creates an installation named kubemq: a container named kubemq and a volume named kubemq-data, with every port bound to this machine only. With Podman, add --runtime podman.

Create the administrator

kmq auth setup --installation kubemq --username admin

When kmq asks, type a new password twice. kmq shows the minimum length.

You should see:

Output

{
  "state": "authenticated",
  "credential": "...",
  "account_id": "...",
  "role": "read_write",
  "next_action": "context_use_then_verify_installation"
}

If kmq reports Management connection failed, the server is still starting: wait a few seconds and run it again. If kmq reports credential_storage_unavailable on Linux, add --credential-backend file.

AI coding agents: a person must type this password, so hand the terminal over. See the AI coding agent section of Install with kmq.

Point kmq at the server

kmq context use kubemq

You should see:

Output

{
  "context": "kubemq",
  "status": "active"
}

kmq auth setup saved a connection named kubemq; this command makes it the one kmq uses.

Send a message

kmq queue send orders '{"id":1}'

You should see:

Output

{
  "messageId": "...",
  "sentAt": "..."
}

On Windows, in PowerShell:

'{"id":1}' | Set-Content message.json

kmq queue send orders --file message.json

Receive it

kmq queue receive orders

You should see:

Output

[
  {
    "messageId": "...",
    "clientId": "...",
    "metadata": "",
    "body": {
      "id": 1
    },
    "bodyBase64": "eyJpZCI6MX0=",
    "timestamp": ...,
    "sequence": 1,
    "tags": "",
    "receivedCount": 1,
    "reRoutedFrom": "",
    "expirationAt": 0,
    "delayedTo": 0
  }
]

Open http://localhost:8080 and sign in as admin to see the orders channel.

These commands are for bash on macOS and Linux. On Windows, run them in WSL (Windows Subsystem for Linux), or use the kmq tab of Try KubeMQ, which runs natively on Windows.

Start a server

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

With Podman:

podman run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

Check that the server is running:

docker ps --filter name=kubemq --format '{{.Names}}: {{.Status}}'

You should see:

Output

kubemq: Up ...

Install with Docker explains each flag.

Create the administrator

Open http://localhost:8080 and create the administrator. If the page does not open yet, wait a few seconds and reload it. You should see the empty dashboard.

Send a message

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

You should see:

Output

{"is_error":false,"message":"OK","data":{...}}

Receive it

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

You should see:

Output

{"is_error":false,"message":"OK","data":{"RequestID":"...","Messages":[{"MessageID":"...","ClientID":"quickstart-curl","Channel":"orders","Body":"eyJpZCI6MX0=","Attributes":{"Timestamp":...,"Sequence":1,"ReceiveCount":1},"Policy":{"MaxReceiveCount":1024}}],"MessagesReceived":1}}

Body is base64 for {"id":1}.

Both tabs create the same container and volume. Use one of them.

This server runs a 14-day evaluation. To keep it and its data, add a license to it: continue on Install with kmq or Install with Docker, matching the tab you used. Plans compared lists your options.

Clean up

kmq deploy remove --installation kubemq

You should see:

Output

{
  "installation_id": "...",
  "state": "runtime_removed_data_retained",
  "target": "docker",
  "resource_id": "...",
  "data_retained": true,
  "next_action": "inspect_retained_data_or_verify_runtime"
}

docker stop kubemq

docker rm kubemq

Both keep the kubemq-data volume, so the same server can start again later.

Data loss: deleting the volume

This deletes every message and the evaluation. A new volume does not guarantee a new evaluation.

docker volume rm kubemq-data

If something goes wrong

A port is already in use. Stop the program that uses it. Install with Docker lists each port.
kmq reports volume already exists. Run step 2 again with --continue-volume, then kmq auth login --installation kubemq --username admin instead of step 3. To start fresh instead, delete the volume as in Clean up.
kmq reports container already exists, or Docker reports that the name kubemq is in use. Run docker stop kubemq and docker rm kubemq; the data stays in the volume. Then start the server again: with Docker, run step 1 again; with kmq, see the bullet above.
The server stops soon after it starts. Run docker logs kubemq. waiting for license.kubemq.io means a network or proxy blocks the server, which retries for about two minutes. See Troubleshooting. This evaluation has finished, already used its evaluation or Signup-free evaluation is unavailable means no evaluation is left here: start with a trial or license key on Install with kmq or Install with Docker.
Anything else. Check docker logs kubemq and Troubleshooting.

Try KubeMQ

Before you start

Run KubeMQ

Install kmq

Start a server

Create the administrator

Point kmq at the server

Send a message

Receive it

Start a server

Create the administrator

Send a message

Receive it

Clean up

If something goes wrong

Next steps

Choose your path

Install with kmq

Install on Kubernetes

Messaging patterns

On this page