Skip to main content

​
Gate Connect Integration

Gate Connect is a powerful network service that makes your Minecraft proxy universally accessible to players worldwide without requiring port forwarding or a public IP address. It’s an ideal solution for:
  • Home servers without public IP addresses
  • Development environments for testing
  • Load-balanced deployments across multiple Gate instances
  • Dynamic infrastructure where IPs frequently change

​
How Gate Connect Works

Gate Connect acts as a bridge between your locally hosted proxy and the global Minecraft community: When enabled, Gate registers itself with the Connect network and receives a free domain: <your-endpoint-name>.play.minekube.net. Players can then connect from anywhere without you needing to configure port forwarding.

​
Quick Setup

​
Step 1: Enable Connect

Add the Connect configuration to your config.yml:
config.yml
connect:
  # Enable Connect integration
  enabled: true
  
  # Your globally unique endpoint name
  # This becomes: my-awesome-server.play.minekube.net
  name: my-awesome-server

​
Step 2: Configure Authentication

You have two options for obtaining a Connect token:

​
Option A: Auto-Generate Token (Easiest)

Simply start Gate with the endpoint name configured. If the name isn’t taken, a token will be auto-generated: 
gate
Gate will automatically create a connect.json file with your token.

​
Option B: Use Connect Dashboard

  1. Visit the Connect Dashboard
  2. Create a new endpoint with your chosen name
  3. Copy the generated token
  4. Create a connect.json file:
connect.json
{
  "token": "YOUR-TOKEN-HERE"
}
Alternatively, set the token via environment variable: 
export CONNECT_TOKEN="YOUR-TOKEN-HERE"
gate

​
Step 3: Verify Connection

Once Gate starts, you should see log messages confirming Connect registration: 
[Connect] Registered endpoint: my-awesome-server
[Connect] Public address: my-awesome-server.play.minekube.net
Players can now connect using my-awesome-server.play.minekube.net!

​
Advanced Configuration

​
Offline Mode Support

Gate Connect supports offline mode (cracked) players, allowing non-premium Minecraft accounts to join:
config.yml
connect:
  enabled: true
  name: my-server
  # Allow offline mode players through Connect
  allowOfflineModePlayers: true
Important Configuration Notes: 
config:
  # Gate can keep online mode enabled
  onlineMode: true
  # Force key authentication (optional)
  forceKeyAuthentication: true
Authentication Flow: When allowOfflineModePlayers: true is set, Connect handles connection injection in offline mode while Gate’s onlineMode: true still authenticates premium players joining directly. This provides the best of both worlds.

​
Load Balancing with Connect

One of Connect’s most powerful features is built-in load balancing across multiple Gate instances. Multiple Gate proxies can share the same endpoint name: 
# Same endpoint name across all Gate instances
connect:
  enabled: true
  name: shared-endpoint-name  # Same name on all instances!
Setup Steps:
  1. Configure first Gate instance with Connect enabled
  2. Copy the generated connect.json token file from the first instance
  3. Deploy additional Gate instances with:
    • Same connect.name in configuration
    • Same connect.json token file
Architecture Example: Benefits:
  • Automatic distribution of player connections
  • Zero-downtime deployments (rolling updates)
  • Horizontal scaling based on player load
  • Built-in redundancy and failover

​
High-Availability Deployment

Combine Connect with Kubernetes for a production-grade, highly available setup:
deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate-proxy
spec:
  replicas: 3  # Multiple Gate instances
  selector:
    matchLabels:
      app: gate
  template:
    metadata:
      labels:
        app: gate
    spec:
      containers:
      - name: gate
        image: ghcr.io/minekube/gate:latest
        env:
        - name: CONNECT_TOKEN
          valueFrom:
            secretKeyRef:
              name: gate-connect
              key: token
        volumeMounts:
        - name: config
          mountPath: /app/config.yml
          subPath: config.yml
      volumes:
      - name: config
        configMap:
          name: gate-config
---
apiVersion: v1
kind: Secret
metadata:
  name: gate-connect
type: Opaque
stringData:
  token: YOUR-CONNECT-TOKEN
Key Features:
  • replicas: 3 - Run three Gate instances for redundancy
  • Connect token - Stored securely in Kubernetes Secret
  • Shared endpoint - All instances use same Connect endpoint name
  • Auto-recovery - Kubernetes restarts failed instances automatically

​
Troubleshooting

​
Authentication Errors

Symptom: “Invalid signature for profile public key” Solutions:
1

Verify Backend Configuration

Ensure backend servers have:
online-mode=false
enforce-secure-profile=false
2

Force Endpoint Refresh

Change your endpoint name temporarily to clear Connect’s cache:
connect:
  name: my-server-temp  # Different name
Restart Gate, then change back to original name.
3

Validate Configuration

Confirm allowOfflineModePlayers: true is set if using offline mode.

​
Chat Disabled Error

Symptom: “Chat disabled due to missing profile public key” Solution: Set enforce-secure-profile=false in backend server’s server.properties

​
Configuration Changes Not Applied

Symptoms: Offline players still can’t join after enabling allowOfflineModePlayers Solutions:
  1. Wait 2-3 minutes - Connect network needs time to propagate changes
  2. Restart Gate - Force re-registration with new settings
  3. Change endpoint name - Force fresh registration if caching persists

​
Connection Issues

Check:
  • Gate logs show successful Connect registration
  • Endpoint name is valid (alphanumeric, hyphens only)
  • Token is correct in connect.json or CONNECT_TOKEN env var
  • Firewall allows Gate to make outbound connections
Verify:
  • All instances use identical endpoint name
  • All instances share same connect.json token file
  • All instances successfully registered (check logs)
  • Instances are actually running and accepting connections
Solutions:
  • Choose a different, unique endpoint name
  • If you own the endpoint, use the token from Connect Dashboard
  • Contact support if you believe the name is wrongly taken

​
Monitoring and Metrics

Monitor Connect status through Gate’s logging: 
# Successful registration
[Connect] Registered endpoint: my-server
[Connect] Public address: my-server.play.minekube.net

# Connection events
[Connect] Session connected
[Connect] Session watcher disconnected by server, reconnecting
Health Checks: Gate automatically maintains the Connect tunnel and reconnects if disconnected. Watch for:
  • Frequent reconnection messages (may indicate network issues)
  • Registration failures (check token validity)
  • Endpoint conflicts (name already in use)

​
Best Practices

Use Descriptive Names

Choose memorable endpoint names that represent your server brand:
  • awesome-survival.play.minekube.net ✅
  • server1.play.minekube.net ❌

Secure Your Token

Treat Connect tokens like passwords:
  • Store in environment variables or secrets managers
  • Don’t commit connect.json to version control
  • Rotate tokens if exposed

Test Offline Mode

Before production, verify offline mode configuration:
  • Test with both premium and cracked accounts
  • Confirm chat and gameplay work correctly
  • Check authentication flow logs

Monitor Connections

Track Connect health and player distribution:
  • Enable debug logging during initial setup
  • Monitor reconnection frequency
  • Track which Gate instances receive connections

​
Migration from Direct Connections

Transitioning from traditional port forwarding to Connect:
1

Enable Connect Alongside Direct Access

Keep your existing port forwarding active while testing Connect.
2

Test with Beta Players

Share the .play.minekube.net domain with trusted players for testing.
3

Update Server Listings

Update your server’s advertised address on server lists and social media.
4

Remove Port Forwarding (Optional)

Once Connect is stable, you can remove port forwarding rules.

​
Getting Help

If you encounter issues not covered in this guide:
  • Check logs - Both Gate and backend server logs contain valuable debugging info
  • Community support - Join the Gate Discord for real-time help
  • GitHub issues - Report bugs with logs and reproduction steps on Gate repository
  • Connect docs - Visit Connect documentation for network-specific information

Load Balancing

Learn about load balancing strategies across Gate instances

Failover Configuration

Configure failover mechanisms for high availability

Connect Network

Official Connect network documentation

Kubernetes Deployment

Deploy Gate on Kubernetes for production

Build docs developers (and LLMs) love

Get started for freeTalk to us