Alpha Preview — This software is under active development. Expect rough edges and breaking changes.
Install Hub

Joining Your Node to a Realm

Connect your Hecate node to your organization's identity and trust boundary.

What is Realm Joining?

A Realm is your organization's namespace in Macula. It holds your identity, apps, certificates, and trust relationships. Every Hecate node must join a Realm before it can participate in the mesh.

Identity

Your node gets a signed certificate from your Realm

Trust

The Realm knows this node belongs to you

Connectivity

Discover and communicate with peers in your Realm

The Join Flow

Node-Realm Join Flow — sequence showing Hecate Node, Macula Realm, and User interactions

Prerequisites

  • Hecate daemon running

    Installed via HecateOS or the install script

  • A Realm account

    Sign in with GitHub to create one

  • Network access

    Your node must reach macula.io over HTTPS (port 443)

Step-by-Step

1

Sign in to your Realm

Go to macula.io/sign-in and authenticate with your GitHub account. A Realm is created automatically if you do not have one yet.
2

Initiate join from Hecate

Click "Join a Realm" in the Hecate desktop app, or run in a terminal:

hecate join
Opening browser to complete login...
Waiting for login... (expires in 10 min)
3

Log in via your browser

A browser window opens automatically. Sign in with GitHub. The Realm verifies your identity, creates an application identity, issues a certificate, and generates a refresh token — all automatically after login.
4

Node receives credentials

The daemon polls in the background. Once you log in, the node receives its credentials: 

Joined successfully!
  Node:  hecate-abc123
  Realm: io.macula.yourname
  Cert:  valid until 2027-02-27
Your node is now part of the mesh.

Security Design

The join flow uses OAuth device authorization. No secrets cross the wire — only the public key leaves the node. Logging in via OAuth from the same device is sufficient proof of intent.

10-minute session TTL
OAuth-based confirmation
Ed25519 keypair per node
TLS-encrypted transport
User login required
Automatic certificate renewal

Troubleshooting

Session expired

The join session is valid for 10 minutes. If it expires, click "Join a Realm" again to start a new session.

Already joined

If your node is already joined to a realm, leave the current realm first, then join again.

Network errors

Verify your node can reach macula.io:

curl -I https://macula.io/api/v1/auth/health

You should get a 200 OK. Check DNS, firewall, and HTTPS (port 443).

Wrong Realm

Leave the realm and join again. Make sure you are signed in to the correct Realm in your browser before the join flow completes.