Skip to main content

Quickstart

Get Sukko running locally and receive your first real-time message in under 5 minutes.

Time to complete

~5 minutes

Prerequisites​

  • Docker installed and running (Install Docker)
  • A terminal (macOS, Linux, or Windows WSL2)

Step 1: Install the Sukko CLI​

brew install sukko-dev/tap/sukko

Verify the installation:

sukko version

Step 2: Initialize and Start Sukko​

Initialize a local environment with default settings (SQLite + Valkey + direct messaging):

sukko init --defaults

This creates a .sukko/config.json with your infrastructure selections and sets up a local context pointing to localhost.

Now start the stack:

sukko up

Docker images are pulled and services start up:

  • Gateway — WebSocket reverse proxy (port 3000)
  • Core — Message server
  • Provisioning — Multi-tenant management API (port 8080)
  • Valkey — Broadcast bus

A demo tenant is automatically created with catch-all routing and public channel rules. Wait for all services to be healthy (~30 seconds):

✓ All services healthy
  Gateway:      ws://localhost:3000
  Provisioning: http://localhost:8080

Step 3: Create a Signing Key​

Generate an ES256 keypair, register the public key with the provisioning API, and save the private key locally:

sukko keys create --generate
Key pair generated.
  Public key registered as "..." for tenant "demo"
  Private key saved to ~/.config/sukko/keys/demo/...

Generate a token with:
  sukko token generate --sub <user-id>

Step 4: Generate a Token​

Create a JWT token for a test user:

sukko token generate --sub user-1

Copy the token — you'll use it in the next steps.

Step 5: Subscribe to a Channel​

Open a second terminal and subscribe to a channel:

sukko subscribe demo.general.chat --token <paste-token-here>
Subscribed to [demo.general.chat]. Press Ctrl+C to stop.

Step 6: Publish a Message​

Back in your first terminal, publish a message:

sukko publish demo.general.chat '{"text": "Hello, Sukko!"}' --token <paste-token-here>

In the subscriber terminal, you'll see:

[demo.general.chat] {"text": "Hello, Sukko!"}

You just sent your first real-time message through Sukko.

Step 7: Clean Up​

When you're done:

sukko down

Next Steps​