How-to

Enable swarm mode

Goal

Transition your agent into swarm mode so multiple machines running the same identity share an encrypted policy file and can coordinate using distributed locks.

Prerequisites

• The agent has at least one policy rule configured (swarm mode requires a non-empty policy)
• You have chosen a Swarm Key — a strong shared secret that all swarm members will use
• You have chosen a quorum storage location that all swarm members can reach (a network file share, a directory in cloud storage, etc.)

Code

using HexaEight.Bridge;
using HexaEight.Bridge.Authorization;

var client = new Client();
var policies = (CasbinAuthorizationProvider)client.Authorization;

// 1. Build up the local policy first (swarm requires non-empty policy)
await policies.AddPolicyRuleAsync(new PolicyRule(
    "*@example.com", "self", "default", "inbound", "allow"));

// 2. Enter swarm mode
await client.EnableSwarmModeAsync(
    swarmKey:          "shared-swarm-secret-2026",
    quorumStorageRoot: "/mnt/swarm-share/agents/billing");

Console.WriteLine($"IsSwarmMode: {client.IsSwarmMode}");

What happens during the transition

1. The SDK fetches a key derived from the Swarm Key.
2. The current policy file is re-encrypted with that key and written to <quorumStorageRoot>/policy.enc.
3. Any other swarm member that later joins with the same Swarm Key will read the same encrypted policy.
4. A distributed lock manager becomes available at client.SwarmLockManager.
5. A file watcher starts monitoring the quorum policy file for changes by other swarm members.

Verify

// Check that the encrypted policy file was written
string policyEnc = Path.Combine("/mnt/swarm-share/agents/billing", "policy.enc");
Console.WriteLine($"policy.enc exists: {File.Exists(policyEnc)}");
Console.WriteLine($"size: {new FileInfo(policyEnc).Length} bytes");

// Quick check that the lock manager works
await using var lockHandle = await client.SwarmLockManager!.TryAcquireLockAsync("test");
Console.WriteLine($"Acquired lock: {lockHandle != null}");
if (lockHandle != null) await lockHandle.ReleaseAsync();

Joining the same swarm from a second machine

On each additional machine, complete activation of the same identity name and then run the same EnableSwarmModeAsync call with:

• The same Swarm Key
• The same quorum storage location

The SDK detects that an encrypted policy already exists at the quorum location and loads it instead of seeding from local rules. All members converge on the shared policy.

Common issues