Get Started

Quickstart

This tutorial gets you from nothing to a working encrypted message in five minutes. You will install the SDK, activate a HexaEight identity, encrypt a message to yourself, and decrypt it.

Prerequisites

• .NET 8 or later, or Node.js 18 or later
• A HexaEight identity license (a single agent license is sufficient)
• About five minutes

Step 1 — Create a project

Create an empty project directory and open a terminal in it.

# .NET
dotnet new console -n MyAgent
cd MyAgent

# Node.js
mkdir myagent && cd myagent
npm init -y

Step 2 — Install the SDK

# .NET
dotnet add package HexaEight.Bridge --prerelease

# Node.js
npm install @hexaeight/sdk@preview

Step 3 — Activate your identity

Before running the activation tool you need three things: knowing your machine's CPU core count, a purchased license that covers at least that many cores, and the HexaEight Authenticator mobile app on your phone (signed in to your email vault).

1. Check CPU cores:

   hexaeight-activate --cpucores

2. Buy a license at hexaeight.com/pricing that covers at least the reported core count. A 6-character license code arrives by email.
3. Run the activation tool:

   # .NET
   dotnet tool install --global HexaEight.Activate
   hexaeight-activate --newtoken
   
   # Node.js
   npx hexaeight-activate --newtoken

4. The tool will prompt for your resource name, a password (press Enter to auto-generate), the license code from email, and offer to display a QR code. Say yes, scan the QR using the Authenticator app within 2 minutes, approve, and press a key when prompted.

When the tool finishes, two files are written to the current directory: env-file (four environment variables your SDK reads at startup) and hexaeight.mac (a small machine-binding file). Both are required at runtime — keep them alongside your project, but do not commit them to version control.

For the full walkthrough — including renewals, custom hostnames, and troubleshooting — see Activating an identity.

Step 4 — Write the program

Replace your project's main file with the code below. It encrypts a message to your own identity and immediately decrypts it.

// Program.cs (.NET)
using HexaEight.Bridge;

var client = new Client();
Console.WriteLine($"I am: {client.Name}");

// Encrypt a message addressed to myself
string envelope = await client.EncryptEnvelopeAsync(
    recipient: client.Name,
    body:      "hello from HexaEight");

Console.WriteLine($"Envelope length: {envelope.Length} bytes");

// Decrypt the envelope
var msg = await client.DecryptEnvelopeAsync(envelope);
Console.WriteLine($"Sender:     {msg.Sender}");
Console.WriteLine($"Body:       {msg.Body}");
Console.WriteLine($"Authorized: {msg.Authorized}");

// index.js (Node.js)
import { HexaEight } from '@hexaeight/sdk';

const he = await HexaEight.connect();
console.log(`I am: ${he.name}`);

const envelope = await he.envelope.encrypt({
    recipient: he.name,
    body:      'hello from HexaEight',
});
console.log(`Envelope length: ${envelope.length} bytes`);

const msg = await he.envelope.decrypt(envelope);
console.log(`Sender:     ${msg.sender}`);
console.log(`Body:       ${msg.body}`);
console.log(`Authorized: ${msg.authorized}`);

Step 5 — Run it

# .NET
dotnet run

# Node.js
node index.js

You should see output similar to:

I am: web0-bliss-cyan-radar84
Envelope length: 842 bytes
Sender:     web0-bliss-cyan-radar84
Body:       hello from HexaEight
Authorized: Allowed

What just happened

1. The SDK read your activation credentials from env-file and hexaeight.mac.
2. It contacted the HexaEight platform once to fetch the shared key for self-to-self communication.
3. It encrypted your message, returning a wire envelope (a long string).
4. It decrypted that envelope, producing the original body, the verified sender name, and an authorisation result.
5. The Authorized field reads Allowed because no policy rules are configured yet (bootstrap mode).

Common issues

Next steps

Now that you have a working installation, the natural next steps are:

• Send a message to a different identity
• Add your first authorisation rule
• Read about the identity model