Skip to main content

​
Broker Options

Solace Agent Mesh supports three broker deployment options:
  1. Existing Solace Broker: Connect to a running Solace PubSub+ broker (cloud or on-premises)
  2. Local Container Broker: Launch a new broker in a Docker or Podman container
  3. Dev Mode: Run without an external broker for local development (not for production)

​
Option 1: Using an Existing Solace Broker

If you already have a Solace PubSub+ broker running (Standard or Enterprise Edition), you can connect to it directly.

​
Prerequisites

  • Running Solace PubSub+ broker (version 9.0+)
  • Broker connection details:
    • WebSocket URL (e.g., ws://broker-host:8008 or wss://broker-host:443)
    • Message VPN name
    • Username and password with appropriate permissions

​
Configuration

1

During Initialization

When running sam init, choose option 1 for broker type:
Which broker type do you want to use?
  1) Existing Solace Pub/Sub+ broker
  2) New local Solace broker container (requires Podman or Docker)
  3) Run in 'dev mode' (all-in-one process, not for production)
Enter the number of your choice: 1
2

Provide Connection Details

Enter your broker connection information:
Enter Solace broker URL endpoint: ws://your-broker-host:8008
Enter Solace broker VPN name: your-vpn-name
Enter Solace broker username: your-username
Enter Solace broker password: ********
3

Verify Configuration

After initialization, verify your .env file contains:
SOLACE_BROKER_URL="ws://your-broker-host:8008"
SOLACE_BROKER_VPN="your-vpn-name"
SOLACE_BROKER_USERNAME="your-username"
SOLACE_BROKER_PASSWORD="your-password"
SOLACE_DEV_MODE="false"

​
Broker Permissions

Your broker user needs the following permissions:
  • Subscribe to topics under your namespace
  • Publish to topics under your namespace
  • Create temporary queues (if using temporary_queue: true)
  • Bind to queues
For production deployments, create a dedicated service account with minimal required permissions.

​
Using Solace Cloud

For Solace Cloud (PaaS):
1

Get Connection Details

From your Solace Cloud console:
  1. Navigate to your service
  2. Click “Connect” tab
  3. Find WebSocket connection details
2

Use Secure WebSocket

Use the secure WebSocket URL:
SOLACE_BROKER_URL="wss://your-service.messaging.solace.cloud:443"
3

Configure Credentials

Use the credentials from your Solace Cloud service:
SOLACE_BROKER_VPN="your-vpn-name"
SOLACE_BROKER_USERNAME="solace-cloud-client"
SOLACE_BROKER_PASSWORD="your-api-token"

​
Option 2: Local Container Broker

Launch a new Solace PubSub+ Standard broker in a container for local development.

​
Prerequisites

  • Docker or Podman installed and running
  • Ports available: 8080, 8008, 55555 (55554 on macOS)

​
Setup Process

1

Verify Container Engine

Ensure Docker or Podman is installed:
docker --version
2

Initialize with Container Option

Choose option 2 during initialization:
sam init
# Select: 2) New local Solace broker container
Or use CLI option:
sam init --broker-type container --container-engine docker
3

Container Deployment

The init process will automatically run:
docker run -d --rm \
  -p 8080:8080 \
  -p 8008:8008 \
  -p 55555:55555 \
  -u 1004 \
  --shm-size=2g \
  --env username_admin_globalaccesslevel=admin \
  --env username_admin_password=admin \
  --name=solace-broker \
  solace/solace-pubsub-standard
On macOS, port 55554 is used instead of 55555 due to system port restrictions.
4

Default Connection Settings

The local broker uses these default credentials:
SOLACE_BROKER_URL="ws://localhost:8008"
SOLACE_BROKER_VPN="default"
SOLACE_BROKER_USERNAME="default"
SOLACE_BROKER_PASSWORD="default"

​
Managing the Container

docker ps | grep solace-broker
# or
podman ps | grep solace-broker

​
Accessing Broker Management

The containerized broker includes PubSub+ Manager:
  1. Open http://localhost:8080 in your browser
  2. Login with:
    • Username: admin
    • Password: admin
  3. Select the default message VPN
The container broker uses default credentials. For production use, always deploy with secure credentials.

​
Option 3: Dev Mode

Dev mode runs all components in a single process without requiring an external broker. Use only for local development.

​
When to Use Dev Mode

  • Local development and testing
  • Learning Solace Agent Mesh
  • Rapid prototyping
  • CI/CD testing environments
Dev mode is NOT suitable for production. It lacks:
  • Scalability across multiple processes
  • Reliability and fault tolerance
  • Distributed deployment capabilities

​
Configuration

1

Enable Dev Mode

Choose option 3 during initialization:
sam init
# Select: 3) Run in 'dev mode'
Or use the dev mode flag:
sam init --dev-mode
2

Dev Mode Settings

In dev mode, the .env file will contain:
SOLACE_DEV_MODE="true"
SOLACE_BROKER_URL="INTERNAL_DEV_BROKER"
SOLACE_BROKER_VPN="dev_vpn"
SOLACE_BROKER_USERNAME="dev_user"
SOLACE_BROKER_PASSWORD="dev_pass"
3

Running in Dev Mode

Start your agent mesh normally:
sam run
All components run in the same process with in-memory message routing.

​
Broker Configuration Reference

The broker connection is configured in shared_config.yaml: 
shared_config:
  - broker_connection: &broker_connection
      dev_mode: ${SOLACE_DEV_MODE, false}
      broker_url: ${SOLACE_BROKER_URL, ws://localhost:8008}
      broker_username: ${SOLACE_BROKER_USERNAME, default}
      broker_password: ${SOLACE_BROKER_PASSWORD, default}
      broker_vpn: ${SOLACE_BROKER_VPN, default}
      temporary_queue: ${USE_TEMPORARY_QUEUES, true}

​
Configuration Parameters

ParameterDescriptionDefault
dev_modeEnable internal dev brokerfalse
broker_urlWebSocket URL (ws:// or wss://)ws://localhost:8008
broker_usernameConnection usernamedefault
broker_passwordConnection passworddefault
broker_vpnMessage VPN namedefault
temporary_queueUse temporary queues for responsestrue

​
Troubleshooting

​
Connection Failures

If agents can’t connect to the broker:
1

Verify Broker is Running

docker ps | grep solace-broker
2

Check Credentials

Verify .env settings match your broker configuration:
cat .env | grep SOLACE_
3

Test Connection

Check agent logs for connection errors:
sam run
# Look for "Connected to broker" or connection errors

​
Port Conflicts

If port 8008 is already in use: 
# Find what's using the port
lsof -i :8008

# Stop the conflicting service or use a different port
docker run ... -p 9008:8008 ... solace/solace-pubsub-standard

# Update your .env
SOLACE_BROKER_URL="ws://localhost:9008"

​
Container Won’t Start

docker logs solace-broker

​
Authentication Errors

If you see “401 Unauthorized” or “Authentication failure”:
  1. Verify credentials in .env
  2. Check user exists in broker with correct permissions
  3. For Solace Cloud, ensure API token is valid
  4. Verify Message VPN name is correct

​
Advanced Broker Configuration

​
High Availability Setup

For production deployments with HA: 
# Use HA broker URLs
SOLACE_BROKER_URL="wss://primary.example.com:443,wss://backup.example.com:443"

​
Compression

Enable message compression for bandwidth optimization: 
# In shared_config.yaml
broker_connection: &broker_connection
  # ... other settings ...
  compression_level: 9  # 0-9, where 9 is maximum compression

​
Custom Queue Names

Disable temporary queues for persistent queue usage: 
USE_TEMPORARY_QUEUES="false"

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us