Cloud Relay

Hexcore provides a relay server that connects multiple Hexdeck instances across different machines. This enables real-time coordination between team members regardless of location.

How it works

Operator A ──WebSocket──▶ Hexcore Relay ◀──WebSocket── Operator B

Each Hexdeck server maintains a WebSocket connection to the cloud relay. Operator presence, intent, and collision data flows through the relay in real time.

Setting up

1. Create a Hexcore

Sign in to Hexcore and click Create Hexcore on the dashboard. Give it a name that matches your project.

2. Get the connect link

On the Hexcore detail page, copy the connect link. This is a hexcore+wss:// URL that identifies your Hexcore.

3. Add the relay target

Make sure your Hexdeck server is running, then add the relay target:

hex relay "hexcore+wss://relay.example.com/ws?p=abc&c=connectCode&n=Team"

This registers the cloud Hexcore as a relay target but doesn't start sharing any projects yet.

4. Select projects to relay

List your active sessions to see which projects are available:

hex relay sessions

Then start relaying a project to the cloud Hexcore:

hex relay include <hexcoreId> ~/Code/my-project

The hexcoreId can be a prefix — just enough characters to uniquely identify the target.

5. Invite teammates

Share the invite link from the Hexcore detail page in the cloud dashboard. Teammates click the link, sign in, choose an operator name and color, and they're added to the Hexcore.

Each teammate then runs the same hex relay commands with the connect link on their machine.

Managing relay targets

# List all configured relay targets
hex relay list

# Stop relaying a specific project
hex relay exclude <hexcoreId> ~/Code/my-project

# Remove a relay target entirely
hex relay remove <hexcoreId>

Managing Hexcores on the cloud dashboard

Each Hexcore on the cloud dashboard represents one coordination workspace. You can:

• Create multiple Hexcores for different projects
• Invite teammates with unique invite links
• View real-time operator presence on the detail page
• Delete a Hexcore if it's no longer needed (admin only)

Connection status

The dashboard shows relay connection status as a colored indicator in the header:

• Green — all relay targets connected
• Yellow — some targets connected
• Gray — no relay connections active

The relay automatically handles reconnection with exponential backoff if the connection drops.

Troubleshooting

"Connection refused" error: Make sure your Hexdeck server is running (hex status).

Operators not visible: Verify all team members have relayed the same project to the same Hexcore target.

High latency: The relay server is optimized for low-latency presence updates. If you experience delays, check your network connection.