# HexaEight - installing, for an agent > You are reading the install procedure as PROCEDURE CARDS. Each card is one job: what it is for, > the exact commands, the rules that must be applied exactly, and what "done" means. Follow the > cards; do not improvise a command that is not in one. ## ONE step is the human's. Every other step is yours. THE LICENCE. `hexaeight-activate newtoken` prompts for a password that must not pass through you and needs a QR code approved in an app on their phone. **You do not run it.** You create the folder, print the command, ask them to run it, and wait. That is the only human step in the whole install. You will also need ONE thing from them, and one decision that is theirs: * a PROVIDER API KEY for the router (Bedrock / z.ai / OpenAI). Do not guess one. * WHICH MODEL. After the key works, `hexaeight-activate models` lists what it can actually reach. SHOW them that list and ASK. It usually spans several vendors at very different prices, so the choice is theirs and it has a cost consequence. ## Start by ASKING, not by installing The first card is not a command. Before anything is installed the person needs the HexaEight Authenticator on their phone and an email vault set up in it - identity lives there, and activation is approved there. Ask the four questions on that card and wait for the answers. There is no offline mode and no flag that skips this. ## THE FOLDERS TWO LAYOUTS WORK. Use the preferred one on a fresh machine; do not convert an existing install. PREFERRED — the licence folder holds ONLY the licence, and each component gets its own folder: ~/hbia-agent licence only: env-file + hexaeight.mac. Nothing installed, nothing runs ~/heia-agent the agent ~/heia-router the router ~/heia-runner a runner (optional) ~/heia-workspace the browser UI's files (optional; its default location is fine too) Why: the credentials sit in one folder that nothing executes out of, so it is obvious what must be backed up and never moved. ALSO FINE — the convention INSTALL.md itself uses, where the agent lives IN the licence folder: ~/hbia-agent licence AND the agent ~/hbia-router the router ~/hbia-workspace the workspace INSTALL.md says outright that these names are "a convention, not a requirement". If the person already has this layout, or prefers it, keep it — do not migrate anything. THE INVARIANT, both ways: every component folder other than the licence folder gets env-file and hexaeight.mac HARDLINKED from the licence folder — `ln`, no `-s`, never `cp`. ASK which layout they want if a machine is fresh and they have a preference; otherwise use the preferred one. Verify a hardlink with `ls -li`: the inode numbers must match. ## Pick the OS cards for the machine in front of you Linux install-preflight-linux then the `Any OS` cards in order macOS install-preflight-macos then the `Any OS` cards, PLUS install-agent-macos-hardening Windows install-preflight-windows-wsl then follow the LINUX path from inside WSL A macOS card on Linux is not a caveat, it is the wrong procedure. ## THREE failures that look like success Every component runs, every check is green, and no turn ever answers: - macOS: the binary is not re-signed after download -> "Killed: 9", reads as a crash - macOS: the jail masks the FOLDER, not the three files -> every engine dies with EPERM - any: engines sealed to an `-oai-` route -> `400 modelCode: does not exist` ## The full source These cards are a retrievable form of INSTALL.md, which is itself written for an AI agent. For detail a card does not carry: install https://github.com/HexaEightTeam/hbia-agent/blob/main/INSTALL.md upgrade https://github.com/HexaEightTeam/hbia-agent/blob/main/UPGRADE.md uninstall https://github.com/HexaEightTeam/hbia-agent/blob/main/UNINSTALL.md ## The cards ------------------------------------------------------------------------------ CARD: install-authenticator-first OS: Any OS ------------------------------------------------------------------------------ intent: Before any command — get the Authenticator on your phone and your email vault set up scope: The one thing that must exist before a single command runs: the person's identity, in the Authenticator app, with an email vault. Installs nothing on the machine. asked as: how do I start; install HexaEight; first step; HexaEight Authenticator; vault setup; do I need an app; getting started preconditions: - none — this is the FIRST card, ahead of every command steps: 1. ask the four questions and wait for the answers via: method: ask-do-not-assume gives: app installed, vault set up, licence code in hand, a name in mind then: →2 2. if anything is missing, tell them exactly what to do and STOP until it is done via: method: why-the-phone gives: all four confirmed then: chain to install-choose-resource-name rules that must be applied exactly: [rule] ASK these, one at a time, and WAIT for the answer. Do not assume any of them and do not run a command until all four are answered. 1. "Do you have the HexaEight Authenticator app on your phone?" If not: App Store or Google Play, search "HexaEight Authenticator". It is FREE. 2. "Have you set up your email vault in it?" The vault IS the person. Every agent becomes a resource under it, which is what puts a provable person behind the agent. Without a vault there is nothing to approve with. 3. "Do you have a licence code?" Bought at store.hexaeight.com, arrives by email. Licensed BY CPU CORES, so the code must cover at least what `hexaeight-activate cpucores` reports on this machine. 4. "What should this agent be called?" — see the next card; do not decide it for them. [definition] Identity lives on the phone, not in a file on the machine. Activation is approved there. There is no way to complete activation without the app. Do not look for a flag, an environment variable or an offline mode — none exists, by design. never: - do not run any install command before the vault exists — activation cannot complete [HARD] - do not explain the whole architecture here; they asked to install it always: - ask; never assume the app is installed because the person seems technical - say the Authenticator is free, since people expect a per-user cost done when: the person confirms: app installed, email vault created, licence code to hand next: install-choose-resource-name example (illustrative): Q: Just install it for me. A: Asks the four questions first. Without the Authenticator and a vault, activation cannot be approved and the install stops halfway. ------------------------------------------------------------------------------ CARD: install-choose-resource-name OS: Any OS ------------------------------------------------------------------------------ intent: Decide what this agent is called — a generated name, or a host on your own domain scope: The name `newtoken` will ask for. A decision, not a command — and the person's to make, not the agent's. asked as: resource name; what should I call the agent; domain based name; generic name; FQDN; can I use my own domain preconditions: - the Authenticator is installed and an email vault exists steps: 1. ask which kind of name they want, and get the exact string via: method: generic-or-domain gives: the resource name to type at the newtoken prompt then: →2 2. warn about the password before they run the command, not after via: method: password-warning gives: the person knows to save the password then: chain to install-licence-human rules that must be applied exactly: [rule] Two kinds of name, and the difference is only whether anyone else needs to recognise it. ASK which they want; do not pick. GENERIC — a generated name such as web0-bliss-cyan-ion97. Right when nothing outside this machine has to recognise the agent. Nothing to set up, and it is the default path. DOMAIN-BASED — a host on a domain you control, such as agent.yourcompany.com. Right when other parties WILL see and trust the name: an agent another company calls, or a runner serving your own users. Use it when the name is part of how people identify you. An agent is identified by a HOST name, never by an email address. Email addresses belong to people; the person is the email VAULT, and the agent is a resource under it. [rule] `newtoken` also asks for a password for this resource. It is NOT the person's identity password, and it CANNOT be changed later. Press Enter to have one generated. Tell the person to save it: the resource's password, its licence code and this machine's hexaeight.mac are tied together, and the password is needed whenever the identity encrypts or decrypts. Never ask them to type it to you, never put it in a command you run, and never write it into a file. never: - never ask the person to tell you the resource password [HARD] - never use an email address as a resource name — agents are hosts, people are emails [HARD] - do not pick the name for them always: - record the chosen name — later cards need it for the router and policy - recommend domain-based when the agent will serve other parties done when: a resource name is agreed, and the person knows the password cannot be changed next: install-licence-human example (illustrative): Q: Other companies' agents will call this one. A: Domain-based: a host on a domain you control, so the name they see is yours. ------------------------------------------------------------------------------ CARD: install-licence-human OS: Any OS ------------------------------------------------------------------------------ intent: The licence — the ONE step the human runs, not the agent scope: Produces env-file and hexaeight.mac in the LICENCE FOLDER, ~/hbia-agent. THE AGENT DOES NOT RUN THIS. It creates the folder, prints the command, and waits for the human. asked as: newtoken; activate licence; licence code; env-file; hexaeight.mac; QR approval; who runs newtoken preconditions: - the Authenticator is installed, a vault exists, a licence code is to hand - a resource name has been chosen steps: 1. create the licence folder (this part IS yours) $ mkdir -p ~/hbia-agent via: tool: shell gives: an empty licence folder then: →2 2. hand the command to the human and WAIT — do not run it $ cd ~/hbia-agent && hexaeight-activate newtoken via: method: hand-it-over gives: the human runs it, answers three prompts, approves the QR on their phone then: →3 3. confirm it worked — this you may run $ ls -l ~/hbia-agent/env-file ~/hbia-agent/hexaeight.mac && cd ~/hbia-agent && hexaeight-activate verify-license via: tool: shell gives: both files present and the licence verifies then: chain to the preflight card for this OS rules that must be applied exactly: [rule] Print the two lines below, ask the person to run them in their own terminal, and WAIT. This is the only human step in the whole install. Why it cannot be yours: newtoken prompts for a password that must not pass through you, and it needs a QR code approved in the app on their phone. Do not run it, do not try to drive its prompts, and do not look for a non-interactive flag — there is none. Tell them: scanning the QR with the Authenticator is the normal path; if the terminal will not render it (a headless server), the URL printed underneath opens the same approval in a browser. [rule] ~/hbia-agent is the licence folder. PREFERRED is that it holds the licence and nothing else, with each component in its own folder — but installing the agent here instead is also fine, and is the convention INSTALL.md uses. Either way the invariant is the same: every OTHER component folder gets these two files HARDLINKED from here (`ln`, no `-s`, never `cp`). They are bound to this machine, and a copy is how people end up with an identity that will not validate. Never move or rename this folder afterwards. If the machine is fresh and the person has no preference, use the preferred layout; if they already have the single-folder layout, keep it and do not migrate. never: - the agent must NEVER run newtoken [HARD] - never ask for, echo, or store the resource password [HARD] - never copy env-file or hexaeight.mac anywhere — hardlink them [HARD] - do not continue past this step hoping to come back to it always: - wait for the human to say it is done, then verify - if verify-license fails, report exactly what it said — do not retry blindly done when: ~/hbia-agent holds env-file and hexaeight.mac, and verify-license passes next: install-preflight-linux, install-preflight-macos, install-preflight-windows-wsl example (verified): Q: Can you just activate the licence for me? A: No — it needs a password that must not pass through me and a QR approval on your phone. Run `cd ~/hbia-agent && hexaeight-activate newtoken`; I will verify it when you are done. ------------------------------------------------------------------------------ CARD: install-preflight-linux OS: Linux ------------------------------------------------------------------------------ intent: Prepare a Linux machine — the tool, and the core count scope: The .NET tool and the core-count check, on Linux x64. Installs no component. asked as: install on Linux; Ubuntu install; prerequisites Linux; bubblewrap; bwrap preconditions: - x64 Linux — arm64 Linux has no published build steps: 1. install the .NET SDK if it is absent, then the tool $ dotnet tool install --global HexaEight.Activate || dotnet tool update --global HexaEight.Activate via: tool: shell gives: hexaeight-activate on PATH, 1.0.32 or newer then: →2 2. check the core count the licence must cover $ hexaeight-activate cpucores via: tool: shell gives: core count then: chain to install-router rules that must be applied exactly: [constant] Linux binaries carry the -linux-x64 suffix. The sandbox is bubblewrap, a sudo install. On Ubuntu 23.10+ bubblewrap may install successfully and still be unable to run. Check it with the sandbox card BEFORE starting the agent, not after. never: - do not install on arm64 Linux — there is no build; install-agent exits 2 [HARD] - do not assume bwrap works because apt reported success always: - keep every folder on the Linux filesystem done when: hexaeight-activate runs and cpucores prints a number next: install-router example (illustrative): Q: Ubuntu 24.04. A: Tool installed, 8 cores; the licence must cover 8. Check bwrap before starting the agent. ------------------------------------------------------------------------------ CARD: install-preflight-macos OS: macOS ------------------------------------------------------------------------------ intent: Prepare a Mac — the tool, the core count, and what differs here scope: The .NET tool and the core-count check, on Apple Silicon. Does NOT cover the two macOS hardening steps — those are their own card, and skipping them looks like success. asked as: install on macOS; Mac install; Apple Silicon; prerequisites Mac; sandbox-exec preconditions: - Apple Silicon — Intel Macs have no published build steps: 1. install the .NET SDK if it is absent, then the tool $ dotnet tool install --global HexaEight.Activate || dotnet tool update --global HexaEight.Activate via: tool: shell gives: hexaeight-activate on PATH, 1.0.32 or newer then: →2 2. check the core count the licence must cover $ hexaeight-activate cpucores via: tool: shell gives: core count then: →3 3. note the binary names and the missing tools before using any Linux recipe via: method: platform-names-macos gives: the osx-arm64 names; no /proc; no ss then: chain to install-router, and to install-agent-macos-hardening once the agent is in rules that must be applied exactly: [constant] Binaries are hexaeight-agent-osx-arm64 / hexaeight-router-osx-arm64. Wherever a guide writes hexaeight-agent-linux-x64, use the osx-arm64 name, or the glob ./hexaeight-agent-*. The sandbox is sandbox-exec, built into the OS: `hexaeight-activate sandbox` should say WORKING with nothing to install. There is no bubblewrap on macOS and nothing to apt-get — if you are installing a sandbox on a Mac you are on the Linux path by mistake. There is no /proc, so any recipe reading /proc//exe is Linux-only. `ss` does not exist; use `lsof -ti tcp:`. never: - do not install on an Intel Mac — there is no build; install-agent exits 2 [HARD] - never apt-get or brew a sandbox on macOS always: - use the osx-arm64 names throughout done when: hexaeight-activate runs and cpucores prints a number next: install-router, install-agent-macos-hardening example (illustrative): Q: M2 MacBook. A: Tool installed; binaries are -osx-arm64; sandbox is built in; two hardening steps pending. ------------------------------------------------------------------------------ CARD: install-preflight-windows-wsl OS: Windows (WSL) ------------------------------------------------------------------------------ intent: Prepare Windows — get to a WSL prompt, then follow the Linux path scope: Getting to a Linux prompt. Everything after this is the LINUX path — this card does not duplicate it. asked as: install on Windows; Windows 11; WSL; does this run on Windows; PowerShell install preconditions: - Windows 10/11 with virtualisation available steps: 1. install WSL $ wsl --install via: tool: shell gives: a working WSL Ubuntu prompt then: →2 2. move into WSL and stay there for every later step via: method: wsl-rule gives: a Linux home directory to work in then: chain to install-preflight-linux — follow the Linux path from here on rules that must be applied exactly: [rule] Run everything at the WSL prompt. The agent, the router and the workspace all run inside WSL, and the workspace is reachable from the Windows browser on localhost. Keep all four folders inside the Linux filesystem (/home/you/...), NEVER under /mnt/c/, or file permissions misbehave. Running under WSL is the recommendation, not a workaround. There is no native Windows binary. never: - never put any of the four folders under /mnt/c/ [HARD] - do not look for a native Windows binary always: - treat every later step as a Linux step done when: a WSL prompt, with the working directory under /home next: install-preflight-linux example (illustrative): Q: Windows 11 — supported? A: Yes, under WSL. From the WSL prompt, follow the Linux cards exactly. ------------------------------------------------------------------------------ CARD: install-router OS: Any OS ------------------------------------------------------------------------------ intent: Install the router into ~/heia-router and give it a provider key scope: The router in its own folder, its provider key, and the model list. Does NOT seal engines. asked as: install-router; provider key; upstreams; which model should I use; Bedrock key; route name; heia-router preconditions: - ~/hbia-agent holds a verified licence - a provider API key from the human steps: 1. make the router folder and hardlink the licence into it run this whole block as one script: ---8<--- mkdir -p ~/heia-router ln ~/hbia-agent/env-file ~/heia-router/env-file ln ~/hbia-agent/hexaeight.mac ~/heia-router/hexaeight.mac ls -li ~/hbia-agent/hexaeight.mac ~/heia-router/hexaeight.mac --->8--- via: method: hardlink-not-copy gives: the same inode number on both lines — proof it is a hardlink, not a copy then: →2 2. install the router into that folder $ hexaeight-activate install-router --dir ~/heia-router via: tool: shell gives: the router binary in ~/heia-router then: →3 3. configure which providers it can reach — the human supplies the key $ cd ~/heia-router && hexaeight-activate upstreams via: tool: shell gives: route names; `upstreams --list` prints them then: →4 4. ask each provider what it will actually serve $ cd ~/heia-router && hexaeight-activate models via: tool: shell gives: the real model list for this key then: →5 5. SHOW the human that list and ask which model to use via: method: model-choice gives: the chosen model — needed when sealing engines then: chain to install-agent rules that must be applied exactly: [rule] Every component folder gets env-file and hexaeight.mac HARDLINKED from ~/hbia-agent. `ln` with no -s. Never cp, never mv, never ln -s. The files are machine-bound; a copy is how an identity ends up failing to validate. A hardlink is the same inode, so there is exactly one set of credentials on the machine. This is what `add-runner --from` does internally, so it is the supported mechanism. [rule] The router must answer before the agent starts. An agent started first reports a licence error that has nothing to do with the licence. Start order is always router, then agent, then workspace. [rule] SHOW the human the model list and ASK which to use. Do not pick. The list usually spans several vendors at very different prices, so the choice is theirs and it has a cost consequence. A route name is not a model name: the route is what the router resolves, the model id is what the provider serves. [rule] Engines must be sealed to an anthropic-shaped route. An -oai- route fails at the provider with `400 modelCode: does not exist`, which reads as a bad model id and is not. Remember this when you reach the engine card. never: - never cp or ln -s the licence files — hardlink them [HARD] - never seal engines to an -oai- route [HARD] - do not choose the model on the person's behalf always: - verify the hardlink by comparing inode numbers with ls -li - start the router before the agent variations: - upstreams --list prints route names without re-running the picker done when: the router folder holds hardlinked credentials, and `models` lists models next: install-agent example (verified): Q: Engine returns 400 modelCode: does not exist, but the model id is right. A: The route shape is wrong. Seal against an anthropic-shaped route, not an -oai- one. ------------------------------------------------------------------------------ CARD: install-agent OS: Any OS ------------------------------------------------------------------------------ intent: Install the agent into ~/heia-agent and seal its engines scope: The agent in its own folder, and the default engine set sealed against the router. On macOS this card is NOT sufficient alone — two further steps apply. asked as: install-agent; agent binary; hexaeight-engine; engine --auto; seal engines; heia-agent; claude engine off the router preconditions: - ~/hbia-agent holds a verified licence - the router in ~/heia-router answers, and a model has been chosen steps: 1. make the agent folder and hardlink the licence into it run this whole block as one script: ---8<--- mkdir -p ~/heia-agent ln ~/hbia-agent/env-file ~/heia-agent/env-file ln ~/hbia-agent/hexaeight.mac ~/heia-agent/hexaeight.mac ls -li ~/hbia-agent/hexaeight.mac ~/heia-agent/hexaeight.mac --->8--- via: method: hardlink-not-copy gives: matching inode numbers then: →2 2. install the agent into that folder, verified against a published hash before it runs $ hexaeight-activate install-agent --dir ~/heia-agent via: tool: shell gives: the agent binary and the hexaeight-engine binary in ~/heia-agent then: →3 3. on macOS ONLY, stop here and apply the two hardening steps via: method: macos-gate gives: a signed binary and a file-level jail mask then: →4 on Linux/WSL; on macOS chain to install-agent-macos-hardening first 4. check a turn can be confined — a GATE, not a diagnostic $ cd ~/heia-agent && hexaeight-activate sandbox via: tool: shell gives: WORKING, or INSTALLED BUT CANNOT RUN then: →5 only if it says WORKING 5. look for a personal Claude config that would override the router $ ls -l ~/.claude/settings.json 2>/dev/null || echo 'none - good' via: method: personal-config-check gives: present or absent then: →6 6. seal the default engines against the router in one pass $ hexaeight-activate engine --auto --dir ~/heia-agent via: tool: shell gives: claude, harness, chat, coding, mission, prepare, runmission — sealed then: chain to install-workspace rules that must be applied exactly: [rule] The agent folder gets env-file and hexaeight.mac HARDLINKED from ~/hbia-agent. `ln` with no -s. Never cp, never mv, never ln -s. The files are machine-bound; a copy is how an identity ends up failing to validate. A hardlink is the same inode, so there is exactly one set of credentials on the machine. Verify with `ls -li` — the inode numbers must match. [rule] Engines must be sealed to an anthropic-shaped route. An -oai- route fails at the provider with `400 modelCode: does not exist`, which reads as a bad model id and is not. [rule] A personal ~/.claude/settings.json overrides HBIA and takes the `claude` engine off the router, producing the same misleading 400 as a wrong route shape. `harness` and `mindmapchat` are immune. If the file exists, TELL the human and ASK before touching it. Never edit a person's own config silently. [rule] On macOS, install-agent-macos-hardening is mandatory before the first turn. Both macOS steps leave every component running and every check green, and both surface as a turn that will not answer. Linux and WSL skip them entirely. never: - do not start the agent when the sandbox cannot run [HARD] - never modify a person's ~/.claude/settings.json without asking [HARD] - do not treat a green install as a working install on macOS always: - treat the sandbox check as a gate: do not start the agent unless it says WORKING done when: the agent folder holds hardlinked credentials and both binaries, sandbox says WORKING, and the boot line reports the sealed engine store next: install-agent-macos-hardening, install-workspace example (verified): Q: Ubuntu says INSTALLED BUT CANNOT RUN. A: Stop. Fix bubblewrap before starting the agent; do not proceed past the gate. ------------------------------------------------------------------------------ CARD: install-agent-macos-hardening OS: macOS ------------------------------------------------------------------------------ intent: Stop a Mac install dying silently — re-sign the binary and narrow the jail mask scope: The two macOS-only steps that each produce a working-looking install in which nothing answers. macOS only — on Linux and WSL this card does not apply at all. asked as: Killed: 9; the engine exited without replying; macOS agent will not start; codesign; quarantine; jail mask; EPERM preconditions: - the agent is installed in ~/heia-agent on macOS steps: 1. clear quarantine and ad-hoc re-sign the binary run this whole block as one script: ---8<--- cd ~/heia-agent xattr -d com.apple.quarantine ./hexaeight-agent-osx-arm64 2>/dev/null codesign -s - -f ./hexaeight-agent-osx-arm64 codesign --verify --strict ./hexaeight-agent-osx-arm64 && echo "signature OK" --->8--- via: tool: shell gives: signature OK then: →2 2. mask the credential FILES, not the folder run this whole block as one script: ---8<--- cd ~/heia-agent cp hexaeight-agent.json hexaeight-agent.json.bak_$(date +%Y%m%d_%H%M%S) python3 - <<'PY' import json, os p = 'hexaeight-agent.json' d = json.load(open(p)) mask = sorted(os.path.join(b, f) for b in {os.path.realpath('.'), os.path.abspath(os.path.expanduser('~/heia-agent'))} for f in ('env-file', 'hexaeight.mac', 'agent.uuid')) d['jail'] = {'enabled': True, 'mask': mask} json.dump(d, open(p, 'w'), indent=2) print(json.dumps(d['jail'], indent=1)) PY --->8--- via: method: file-level-mask gives: jail.mask listing env-file, hexaeight.mac and agent.uuid then: →3 3. prove BOTH halves — the engine starts AND the credentials stay hidden run this whole block as one script: ---8<--- cd ~/heia-agent M=$(python3 -c "import json;print(' '.join('(subpath \"%s\")'%m for m in json.load(open('hexaeight-agent.json'))['jail']['mask']))") P="(version 1)(allow default)(deny file-read* $M)" /usr/bin/sandbox-exec -p "$P" ~/.heia/runtime/node_modules/.bin/claude --version /usr/bin/sandbox-exec -p "$P" /bin/cat env-file --->8--- via: method: prove-both-halves gives: a version from the first, 'Operation not permitted' from the second then: back to install-agent step 4 rules that must be applied exactly: [rule] By default the jail hides the agent's whole current directory. On Linux the engine is moved out of that folder before it starts, so it never notices. On macOS it is NOT moved, so it starts inside a directory it may not read and dies immediately with EPERM. Mask the credential FILES instead of the folder — same protection, and the engine can start. List both path forms (/Users/... and /Volumes/Macintosh_HD/Users/...): macOS reaches one directory by two names through a firmlink. Back up hexaeight-agent.json first. [rule] A version number from the first command PLUS 'Operation not permitted' from the second is the pass. Both halves matter; one without the other is a failure. A version with a READABLE env-file means the mask is wrong and the engine can read the licence — stop and fix it. EPERM from the FIRST command means the mask still covers the whole folder. This is narrower than the Linux default: the engine can still read other files in the folder (sessions.he, engines.he), which are encrypted at rest. never: - never mask the folder on macOS — it kills every engine turn [HARD] - do not read 'Killed: 9' as a crash or a corrupt download always: - re-run the codesign step after EVERY download or upgrade of the agent binary - back up hexaeight-agent.json before rewriting it variations: - `-s -` is an ad-hoc signature: no developer account and no identity required done when: codesign --verify --strict passes, and the two sandbox-exec probes give version + EPERM next: install-agent example (verified): Q: The shell prints Killed: 9 and the ports stay closed. A: Unsigned after download. Ad-hoc re-sign it — this is a signature failure, not a crash. ------------------------------------------------------------------------------ CARD: install-workspace OS: Any OS ------------------------------------------------------------------------------ intent: Put the browser workspace up, and prove the whole chain end to end scope: The workspace on port 5620, and the one check that actually proves the install. asked as: install-workspace; workspace on 5620; browser UI; host the workspace; prove it works preconditions: - the agent in ~/heia-agent is sealed, and the router answers steps: 1. install the workspace $ cd ~/heia-agent && hexaeight-activate install-workspace via: tool: shell gives: the browser UI on 5620 then: →2 2. open it, sign in as the owner, and ask it a question via: method: end-to-end gives: an answer in the browser then: chain to install-autostart rules that must be applied exactly: [rule] A question answered in the browser is the only proof the whole chain works. A listening port proves nothing about the router, the seal or the engine behind it. On Windows the workspace runs inside WSL and is reached from the Windows browser on localhost. It can also be hosted as a static site — see step 6 of INSTALL.md. never: - do not treat a listening port as a working install always: - verify by asking a real question, not by checking the port done when: a question asked in the browser comes back answered next: install-autostart, install-runner example (illustrative): Q: Port 5620 is listening — are we done? A: Not yet. Ask it something; the port says nothing about what is behind it. ------------------------------------------------------------------------------ CARD: install-autostart OS: Any OS ------------------------------------------------------------------------------ intent: Make it all come back after a reboot scope: Start order at login. Without this, nothing comes back. asked as: autostart; survive reboot; start on login; nothing came back after restart preconditions: - router, agent and workspace all work steps: 1. turn autostart on $ cd ~/heia-agent && hexaeight-activate autostart on via: tool: shell gives: router, then agent, then workspace at login — in that order then: →2 2. hand over the URL and the folder layout via: method: handover gives: the person knows where to click and what not to move then: done rules that must be applied exactly: [rule] Finish by telling the person the workspace URL and what they can do there. Order matters on every start: router, then agent, then workspace. Also tell them the four folders and which one is the licence — ~/hbia-agent must never be moved or renamed. never: - never start the agent before the router [HARD] always: - state explicitly that without autostart nothing returns after a reboot done when: autostart is on, and the person has the URL and the folder layout next: install-runner, upgrade-components example (verified): Q: After rebooting, nothing is running. A: autostart was never turned on — it is not the default. Turn it on. ------------------------------------------------------------------------------ CARD: install-runner OS: Any OS ------------------------------------------------------------------------------ intent: Add a runner in ~/heia-runner — a second agent serving one sealed mission to outsiders scope: OPTIONAL, and only when outside callers or your own users need to reach a single fixed procedure. Not part of a basic install. asked as: add-runner; add-external-agent; runner agent; front door; serve outside callers; heia-runner preconditions: - the main agent works end to end - a mission exists to seal, if one is being sealed steps: 1. create the runner from the licence folder — it hardlinks the identity itself $ hexaeight-activate add-runner --from ~/hbia-agent --dir ~/heia-runner via: tool: shell gives: a runner folder with hardlinked credentials and its own ports then: →2 2. confirm the identity is shared by hardlink, not copied $ ls -li ~/hbia-agent/hexaeight.mac ~/heia-runner/hexaeight.mac via: method: runner-is-separate gives: matching inode numbers then: →3 3. note how to stop things on this machine from now on via: method: folder-blind-stop gives: stop by PID or per-folder script, not by hexaeight-activate stop then: done rules that must be applied exactly: [rule] A runner is its OWN folder and its own agent process, sharing the identity by hardlink. `add-runner --from` does the hardlinking itself — do not pre-create the files. --from supplies the IDENTITY ONLY: its hexaeight.mac and env-file are hardlinked into the new folder, never copied. Two agents under one identity that share a folder also share sessions, engines and ports — which is why the runner gets its own. [rule] `hexaeight-activate stop` and `restart` are FOLDER-BLIND on a multi-agent machine. They match every agent process, so running them from the runner folder also stops the main agent. On a machine with a runner, stop a component by its own PID or use a per-folder script. True as of Activate 1.0.65. never: - never run two agents out of one folder — they share sessions, engines and ports [HARD] - never use `hexaeight-activate stop` on a machine with a runner — it is folder-blind [HARD] - do not add a runner as part of a first install unless it was asked for always: - give the runner its own folder, always variations: - `add-external-agent` is the same command; `add-runner` is the alias - `modify-agent --dir ` changes an existing runner's peer, owner, tiers or ports done when: the runner folder exists with hardlinked credentials and its own ports next: upgrade-components example (verified): Q: I ran stop from the runner folder and my workspace died. A: Expected — stop matches every agent. Stop by PID, or use a per-folder script. ------------------------------------------------------------------------------ CARD: upgrade-components OS: Any OS ------------------------------------------------------------------------------ intent: Upgrade to a newer release scope: Replacing a component and restarting only that one. What each release changes, and any per-release ordering, is in UPGRADE.md — this card does not duplicate it. asked as: upgrade; new version; hexaeight-activate update; whats-new; update the agent preconditions: - a working install steps: 1. see what changed before upgrading anything $ cd ~/heia-agent && hexaeight-activate whats-new via: tool: shell gives: the release notes then: →2 2. read the release-specific procedure $ https://github.com/HexaEightTeam/hbia-agent/blob/main/UPGRADE.md via: method: read-upgrade-doc gives: the ordering and any per-release step then: →3 3. replace one component and restart only that one $ cd ~/heia-agent && hexaeight-activate update via: tool: shell gives: the upgraded component then: →4 on macOS; otherwise done 4. on macOS ONLY, re-sign the replaced binary via: method: resign-after-upgrade gives: signature OK then: done rules that must be applied exactly: [rule] Read UPGRADE.md for the release in hand before running the upgrade. Per-release ordering is not guessable from the tool's output. [rule] Any macOS download or upgrade of the agent binary needs the codesign step again. Otherwise it dies with Killed: 9 and nothing explains why. never: - do not upgrade without reading what the release changes always: - upgrade one component at a time - on a machine with a runner, upgrade each folder and restart by PID done when: the component reports the new version and still answers a question next: install-agent-macos-hardening example (verified): Q: Upgraded on a Mac and now nothing starts. A: Re-sign the replaced binary — the upgrade discarded the ad-hoc signature.