Concept

The scaling model (swarm)

A single logical agent often needs to run on more than one machine — for throughput, redundancy, or geographical distribution. HexaEight calls this configuration a swarm. This page describes the swarm model conceptually. The How-to section contains the practical steps for enabling it.

The starting situation

Suppose you have one agent identity and you want to run it on two machines. Each machine activates the same identity locally (a separate activation per machine). After activation, both machines can independently encrypt and decrypt messages addressed to that identity.

What they cannot do, in this default configuration, is share state securely. Each machine has its own policy file, its own audit log, its own in-memory caches. If you want them to behave as a single logical agent — enforcing the same rules, coordinating on shared resources — you need to enable swarm mode.

What swarm mode adds

Enabling swarm mode on each machine accomplishes three things:

1. A shared, encrypted policy file stored at a location both machines can reach (network file share, cloud storage). Any change one machine makes to the policy is visible to the others.
2. A distributed lock primitive the swarm members can use to coordinate writes to any shared resource (the policy itself, a task queue, an audit log).
3. Change detection so each machine's in-memory state is kept current as other machines make updates.

The Swarm Key

All swarm members share a secret called the Swarm Key. The Swarm Key is the encryption key for the shared policy file and for the lock files used by the distributed lock primitive. It is supplied to the SDK by the application; HexaEight never holds it.

Distributing the Swarm Key to swarm members is the application's responsibility. The standard pattern is to use the JWT handshake (one of the SDK's first-contact identity assertion mechanisms) to deliver the Swarm Key to new members as they join.

Swarm mode is irreversible

When you enable swarm mode on a particular machine, you do not go back to single-machine mode on that machine without reinstalling. The SDK re-encrypts the local policy file with the Swarm Key, and the previous self-encryption key is lost. To revert, you wipe the agent's activation files and reactivate from scratch.

This is by design — the cryptographic property that makes swarm sharing safe is the same property that prevents a clean rollback.

What sharing looks like in practice

Once swarm mode is enabled on every machine:

• Adding a rule on Machine A immediately makes it visible on Machine B.
• An incoming message arriving at any swarm member is enforced against the same policy.
• A long-running task can claim a lock on any swarm member, preventing duplicate work on the others.
• Audit log entries are written by each machine separately (each machine has its own log) but all reference the same policy.

Storage backends

The shared policy file and lock files need to live somewhere all swarm members can reach. The SDK ships with a local-filesystem implementation that works on:

• Local disks (single-machine multi-process scenarios)
• Network file shares (SMB, NFS, AWS EFS)
• Any other filesystem that supports atomic file creation

For cloud object stores (AWS S3, Azure Blob, Google Cloud Storage), reference implementations of the storage interface will be published in a separate adapters repository. The cryptographic logic is identical; only the read/write/lock primitives change.

What swarm mode does NOT do

Swarm mode shares policy and provides locks. It does not:

• Distribute messages among swarm members (your application chooses which machine receives which message)
• Implement work-queueing or load balancing (those are application concerns)
• Synchronise message-level state like sessions (each session is between a specific sender and receiver pair)
• Replace your overall orchestration platform — it provides primitives, not a complete framework

The SDK gives you the building blocks. You compose them into the coordination pattern your application needs.