Encrypted stores

The agent keeps its access rules, engines, sessions, approvals, consent records and other settings in encrypted stores: the .he files in its folder. Each one opens only with this agent’s identity.

The check at every start

Before the agent opens its port, it opens every store, one at a time. If one does not open, the agent does not start, and it says which store and what to do. Starting without it would leave the agent broken in a way nobody notices: a policy that cannot be read looks like no rules, and a terms store looks like nobody ever accepted.

• The key is tried first. A store that does not open gets freshly fetched keys, three tries 20 seconds apart, before anything is decided about the file.
• Every store is checked, even after one fails, so one message lists everything to fix.
• Last-good copies. After every start that passes, the agent keeps two copies of each store that opened: .lastgood and .lastgood.2.
• Nothing is repaired without you. Putting a copy back is a person’s decision, made with restore-store (below). The one exception is the signed-in sessions file (sessions.he): if it does not open but its last-good copy does, the agent puts the copy back itself.

The reason for a stop is in the agent’s log and in startup-check.json in the agent’s folder.

When the agent does not start

What the check finds	What to do
A store’s key cannot be fetched	Start the agent again in a few minutes. The keys that worked are kept, so only the missing one is fetched. If it keeps failing, check the licence: hexaeight-activate verify-license.
A store does not open, but one of its last-good copies does	The key is fine and the latest file is not. Start the agent again to retry. If it still stops, put the copy back with restore-store.
A store does not open, and neither do its last-good copies	Those copies opened before, so the key is the problem, not the files. Start the agent again.
The folder’s stores belong to a different identity from the one in env-file	Another identity’s keys cannot open them. Put back the env-file of the identity the stores belong to, or start the new identity from a folder of its own.
The licence has expired	Renew it with hexaeight-activate, then start the agent again.

The exit status tells a script or service manager which case it is: 75 means a key could not be fetched (try again later), 65 means a store did not open while its copy did, and 78 means the folder belongs to another identity.

What does not stop a start:

• A store with no last-good copy to compare with, for example a file from an older version. The agent starts without what that store holds, as older versions did. The file is not touched, and it is named in the log and in the audit trail.
• Preferences (prefs.he). If they do not open, the file is renamed aside, never deleted, and a new one is written. This happens only on a start where every other store opened.
• A store that does not exist yet.

Check the stores yourself

cd ~/heia-agent
./hexaeight-agent-linux-x64 hexaeight-agent.json check-stores

It runs the same check and reports the result. It changes nothing, so it is safe while the agent runs. On macOS the binary is hexaeight-agent-osx-arm64.

Put a last-good copy back

Stop the agent first, then run this in a terminal:

./hexaeight-agent-linux-x64 hexaeight-agent.json restore-store policy.csv

Name the store the message named. Before changing anything, restore-store:

• tries fresh keys on the current file, and does nothing if it opens
• shows the copy it would use and when it was taken. Anything written after that time is not in the copy.
• waits until you type restore

The file that did not open is kept beside it, renamed, never deleted. The restore is recorded in the audit trail. Then start the agent.

Next

• Lifecycle: start, stop, update
• Troubleshooting