Get Started

Activating an identity

What activation does

Activation binds a HexaEight identity to a specific machine. When it completes, the machine has the credentials it needs to send and receive encrypted messages as the named identity. Two files are produced: env-file (four environment variables the SDK reads at startup) and hexaeight.mac (a small machine-binding file).

Prerequisites

• The HexaEight Authenticator mobile app installed on your phone
• An email vault registered in the Authenticator app
• A web browser open and ready (for scanning the QR code shown during activation)
• The SDK installed in your project (see Installation)

Step 1 — Determine your machine's CPU core count

HexaEight licenses are sized by CPU core count. Before purchasing, check how many cores your machine reports:

hexaeight-activate --cpucores

Expected output:

CPU Count   : 1
Total Cores : 4

Buy a license that covers at least the total core count shown. A license sized below your machine's cores will be rejected during activation.

Step 2 — Purchase a license

Buy a license at the HexaEight store: hexaeight.com/pricing.

After purchase, you will receive an email containing a 6-character license code (for example, Qmmrj.). This code is what you enter during activation.

Step 3 — Decide on a resource name

The resource name is the identity name the agent will be known by. You choose this before activation. Two forms:

• Custom hostname — a hostname under a domain you control (for example, agent01.acme.com). Requires a DNS TXT proof of domain ownership step. Use the Authenticator mobile app to generate the entry for the hostname first.
• Generic resource — an auto-generated handle in the form web0-bliss-cyan-<rotating-word>. Generated through the Authenticator mobile app.

Step 4 — Run the activation tool

From your project directory:

# .NET
hexaeight-activate --newtoken

# Node.js
npx hexaeight-activate --newtoken

The tool prompts you, in order, for:

1. Resource name —

   Enter Resource Name :

   Type the resource name you chose in Step 3.
2. Password —

   Enter New Password For Your Resource : [Press Enter to Generate a Password]

   Press Enter to have the tool generate a strong password, or type your own.
3. License code —

   Enter the License Code Received in your Email :

   Type the 6-character code from the purchase email.
4. QR code display option —

   Do You Want to Display A QRCode ? [Y/N]

   Enter Y. The tool prints a URL like https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=... — open this in your browser so the QR code is visible on screen.

Step 5 — Authorise the activation from the Authenticator app

On your phone, open the HexaEight Authenticator app and scan the QR code displayed in your browser. The app will show an authorisation entry for the resource name you supplied. Approve it.

Step 6 — Confirm completion

Back in the activation tool, you will see:

Press Any Key Once QR Code Has Been Authorized Using HexaEight Authenticator Mobile App...

Press Enter. The tool will display the credentials it received and write the activation files.

Result

Two files appear in the directory where you ran the tool:

Renewing a license

When your license is approaching its expiry, purchase a renewal at the same store. You will receive a new 6-character license code by email. Run the renewal flow:

# .NET
hexaeight-activate --renewtoken

# Node.js
npx hexaeight-activate --renewtoken

The tool prompts only for the new license code:

Enter the License Code Received in your Email :

The renewal updates the HEXAEIGHT_MACHINETOKEN value in env-file. Restart your application for the change to take effect.

Common issues