Multiplayer for self-hosted Retool Apps

Learn how to set up multiplayer apps on a self-hosted deployment.

Multiplayer Availability
Cloud-hosted	Generally Available	Available on all plans
Self-hosted (3.272 Edge)	Public beta	Available on all plans
Self-hosted (3.196 Stable and later)	Public beta	Available on all plans

Multiplayer enables multiple users to make changes to the same app simultaneously. Similar to collaborative editing tools like Google Docs, users can see what others are working on and changes are reflected in real-time.

Use the instructions in this guide to set up multiplayer on a self-hosted deployment, which requires additional configuration.

Prerequisites

Navigate to Settings > Beta and turn on the Enable multiplayer editing org wide setting.

Multiplayer infrastructure

Enabling multiplayer for self-hosted Retool requires making several infrastructure changes:

1. Deploy a new multiplayer service. This service manages the real-time editing state.
2. Update your frontend proxy to route multiplayer traffic to the new multiplayer service.

Loading diagram...

The multiplayer service and the Retool editor frontend maintain a WebSocket connection. The multiplayer service also requires the ability to connect to the main Postgres database.

The following sections include more details about making this architecture change using Retool's official retool-helm chart or a non-helm deployment.

Configuring multiplayer with Kubernetes Helm

Using the official retool-helm chart is the easiest way to set up multiplayer.

Enable the service by setting the multiplayer: enabled option in your values file.

You can also opt-in to use Retool's preconfigured ingress rules, or you can configure them manually.

Configuring multiplayer for non-Kubernetes Helm deployments

First, provision resources to run the multiplayer service. Then, complete the steps in the following sections.

Set environment variables

Set the following environment variables for the new container:

# Multiplayer-specific environment variables
SERVICE_TYPE=MULTIPLAYER
MULTIPLAYER_SERVER_PORT=3009 # Configure to match your proxy settings (see Configure web proxy section).

# Standard required environment variables. Their values should match the values used for the existing Retool backend service.
COOKIE_INSECURE
WEBSOCKET_ALLOWED_ORIGIN # Supports '*' wildcard
POSTGRES_HOST
POSTGRES_PORT
POSTGRES_DB
POSTGRES_USER
POSTGRES_SSL_ENABLED
POSTGRES_PASSWORD
ENCRYPTION_KEY
JWT_SECRET

Configure web proxy

Configure the web proxy to route traffic for api/multiplayer/* to the new multiplayer service. All other traffic should route to the regular Retool backend service.

The following code snippet is an example nginx configuration that achieves this. Note that this example does not include SSL termination and omits unrelated settings, so your actual config may look slightly different.

# nginx/nginx.conf

http {
  map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
  }

  server {
    listen 80;
    server_name retool.app.localhost;
    error_log /var/log/nginx/retool80.error_log debug;

    location /api/multiplayer/ {
      proxy_pass http://multiplayer:3009/api/multiplayer/;

      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_set_header Host $host;
    }

    # Existing configuration to route traffic to Retool's API.
    # This config must come after the /api/multiplayer config above since
    # it is less specific.
    location / {
      proxy_pass http://api:3000/;

      resolver 127.0.0.11 valid=30s;
      add_header X-XSS-Protection "1; mode=block";
      add_header X-Content-Type-Options nosniff;
    }
  }
}

Verify functionality

To verify that the feature is working, open an app in the Retool editor. If the multiplayer feature is enabled, you will see your avatar on the right side of the status bar.

The Network tab should show a WebSocket connection. The Status column should say 101 and the Time column should say Pending because the connection is left open.

WebSocket connection

The following screenshot shows example connection details. The expected response Status Code is 101 Switching Protocols.

Example connection details

Troubleshooting

If multiplayer functionality isn’t working, or you see many repeated connection attempts in the Network tab, the proxy likely isn’t configured correctly. To confirm traffic is reaching the multiplayer service, check the service’s logs for messages such as “Handle updated request for <url>” and “Handle new connection for <uuid>...”.

If you have any issues, please reach out to Retool Support and send your multiplayer service logs.