Reference
Mac setup & daily controls
Save setup once, pair an agent with a code, then start, inspect and stop Holocron.
Set up once, pair each receiver with a temporary code and native approval, then use holocron start, status and stop.
This guide targets 0.3.6 and its public GitHub release. Previous published releases remain immutable. Real device/native GUI acceptance is still pending.
Mac setup
Use your existing dedicated relay admin token file: canonical absolute path, 0600, under a 0700 parent. Supply its value through your trusted local credential workflow, such as Fidelius. No Mac tunnel or relay credential goes to the receiver.
curl -fsSL https://holocron.ashray.xyz/setup.sh | sh -s -- \
--admin-file /absolute/private/relay-admin-token
Setup installs missing pinned Node locally, verifies the public GitHub release, builds the AppKit approval helper and reuses your linked Holocron or Board config. Fresh setup creates a private STDIO config. It starts no service. Complete the native Command Line Tools installer when required, then repeat setup.
Add ~/.local/bin to PATH, or use $HOME/.local/bin/holocron. Repeating holocron setup retains the saved setup and refreshes an older owned helper while the operator is stopped. Existing permissions, unrelated jobs and old profiles are not silently migrated.
Save your existing local MCP tunnel references once:
holocron setup --tunnel-profile /absolute/private/existing-tunnel.yaml \
--tunnel-client /absolute/path/to/tunnel-client
The private profile retains its existing tunnel identity, control-plane settings, workspace associations and credential references. Holocron supplies the installed STDIO main command internally for its owned run. It provisions no tunnel or account. The official tunnel client/profile must already be installed and authorized. Setup resolves package-manager executable aliases such as /opt/homebrew/bin/tunnel-client once and saves their guarded canonical target. If a package upgrade removes that target, repeat setup with the alias to bind the new executable. Stop a manually running tunnel through its existing owner before switching supervision.
For an existing unlinked Board config, add --local-config /absolute/private/local.json. To reuse an existing secret pairing explicitly, add --mac-config /absolute/private/mac.json. --prompt /absolute/private/helper reuses an operator-managed helper; use the 0.3.6 helper for masked typing and Cmd+V. The default build supplies it and the existing green H app icon, rasterized from the site’s favicon asset. Native Edit menu actions follow the focused AppKit field editor, as in Fidelius; secure fields retain native masking and copy/cut restrictions. AppKit responder-chain behavior explains this routing.
Upgrade a saved Mac setup
Publish the new release and deploy any required relay update first. Stop the existing owned supervisor, then install and rebuild from 0.3.6:
holocron stop
hc_bootstrap=$(mktemp)
curl -fsSL https://holocron.ashray.xyz/install.sh -o "$hc_bootstrap"
sh "$hc_bootstrap" --version 0.3.6
rm -f "$hc_bootstrap"
"$HOME/.local/bin/holocron" --version
"$HOME/.local/bin/holocron" setup --rebuild-prompt
"$HOME/.local/bin/holocron" start
The version check must print 0.3.6. Keep the same HOLOCRON_CLI_HOME override, if your setup uses one. Setup builds in a fresh private versioned directory, copies its icon, and atomically saves the new helper reference only after success. It retains pairing credentials, expiry, pending recovery, Board state and tunnel references. Older helpers remain for existing explicit pairing-file commands. Build/save failures retain the previous setup and remove only the new owned helper. No fresh pair is needed. Ordinary setup also refreshes older generated helpers; external --prompt helpers stay operator-controlled until explicitly rebuilt. Setup refuses while the owned supervisor runs. Restarting makes the new code and helper effective for saved services.
Receivers should install 0.3.6 with the same installer command to obtain the full fifteen-minute request window. Existing saved pairings remain compatible. Earlier clients still use their earlier deadline limits; upgrade both endpoints before new code pairing.
Pair a receiving computer
holocron pair
Give the printed fifteen-minute code to your intended receiver through your trusted conversation. They run the single setup command and give you eight verification digits. Enter them in the native Mac prompt, review recipient/relay/expiry, then choose Approve pairing. The prompt does not reveal the expected number.
One code admits one receiver proposal. Mismatch, cancellation or expiry requires a fresh code. Saved pairing lasts seven days; every key request still needs native approval. A code alone grants no lasting authority.
Start, inspect and stop
holocron start
holocron status
holocron stop
start runs the configured tunnel and active saved secret services in the foreground. Keep its terminal/process supervisor running and the Mac awake. Ctrl+C or stop shuts down only that owned supervisor and its children. A repeated start reports the active owned runtime.
Status distinguishes configured/stopped, service failure, relay reachability and tunnel readiness. A running process does not establish remote discovery. Private loopback /readyz provides tunnel readiness when available; otherwise it stays unverified. Backend/tunnel failure closes active prompts and stops the owned run. Restart deliberately after recovery.
With saved setup, bare status and stop address these components. Explicit --local-config FILE or --config FILE retains the original companion contract. Without saved setup, bare status/stop retain linked-profile behavior. Clipboard, MCP, Raycast and HTTP commands remain compatible.
Revoke a receiver
Locally identify the Mac config path from your private setup references, without displaying credential contents:
holocron secrets revoke --mac-config /absolute/private/pairings/PAIR/mac.json
Success is {"revoked":true}. Stop the service and retain its config until acknowledgement. Local deletion cannot revoke authority or erase received/downstream copies. A revoked saved service fails closed; after acknowledged revocation, remove only its reference from your private setup. Legacy explicit secrets serve --mac-config FILE remains available.
Pairing recovery
| Result | Action |
|---|---|
| Wrong, expired or already used code | Run holocron pair again |
pairing_peer_mismatch |
Cancel, confirm the intended computer, then use a fresh session |
pairing_incomplete_revoke_mac_config |
Run holocron pair --recover; acknowledgement or actual expiry is required |
unsafe_tunnel_client |
Check executable ownership, write permissions and target; repeat setup with the trusted installed alias |
| Interrupted helper build or old helper behavior | Stop the owned run and use holocron setup --rebuild-prompt; builds use a fresh directory and preserve existing helpers |
| Stale owned runtime socket | Run holocron setup --recover, then start |
setup_busy_or_interrupted_inspect_setup_lock |
Verify the other setup exited, then remove only its empty private setup.lock directory |
| Expired receiver | Get a fresh code and repeat receiver setup with --renew |
Failures preserve completed pairings. Uncertain provisioning retains the new Mac credential for revocation. Receiver failures remove only their newly owned directory. No automatic retry can reopen a prompt or pick another peer.
Relay operator reference
Reuse the configured Vercel/Upstash backend. The function needs UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN and the dedicated HOLOCRON_SECRETS_ADMIN_TOKEN. Release operations cover publication; preserve earlier tags/assets.
POST JSON rejects browser Origins/query strings, uses no-store responses and sanitizes backend failures. Stored state contains public commitments/keys, credential hashes, metadata and ciphertext. Disable external payload/header capture and redact Authorization.
Code sessions last fifteen minutes with atomic one-proposal transitions, one ciphertext consumption and a 15-minute reuse tombstone. Global code traffic is bounded at 600 operations/minute. Channel quotas remain ten requests/hour and 240 operations/minute. A compromised relay can deny service. Clocks must be accurate; both endpoints need HTTPS.
Security and expiry reference
The 20-character base32 code pins 100 bits of a SHA-256 Mac commitment covering relay, expiry, random nonce and X25519 key. The receiver commits its signed descriptor/nonce before the Mac reveals its key. Both verify commitments locally. HKDF over X25519 and the canonical transcript yields the eight-digit verification number. One native prompt accepts one attempt and never displays the expected answer.
This is a commitment-based short authentication flow, not a password protocol. A substituted receiver gets one guess per locked session, about one in 100 million. Fresh attempts require deliberate human action. Trusted delivery of the public code pins the Mac; trusted delivery and native entry of the receiver’s number authenticates the receiver. Never accept relay-supplied replacements.
Enrollment binds the complete descriptor and pinned Mac key. Ed25519-signed requests and NaCl box deliveries preserve authenticated endpoint binding and secrecy with a compromised relay. Receiver credentials remain local. Names/recipient/purpose are public metadata; values are nonempty exact UTF-8 up to 4,096 bytes, without NUL or trimming.
Pairing code sessions and key requests expire after fifteen minutes from creation. The prompt shows the exact deadline; joining a session late or approaching the seven-day pairing expiry leaves less time. Received plaintext files still auto-delete five minutes after receipt, independently of approval time. Sleep/power loss/worker termination can delay removal. Same-user malware, endpoint memory and downstream copies remain within the endpoint trust boundary; secure erasure is not promised.
The commitment rationale follows RFC 6189 section 4.4.1.1, without implementing ZRTP. The existing unsuppressed site advisory GHSA-ch52-4w7c-c8xp remains separate.
Acceptance on your devices
- Pair the actual receiver and observe native number entry/approval. Run the harmless PASS/FAIL check before real values. For paste acceptance, manually copy only
holocron-acceptance-2026, focusTEST_API_KEY, type a character, press Cmd+A then Cmd+V, and confirm masked bullets. Repeat with Edit > Paste, then approve and expect PASS. Confirm the native Dock/app-switcher uses the same green H as the website. This deliberately replaces your clipboard with harmless test text; perform it yourself when ready. - Observe native Cancel, receiver Ctrl+C, wrong code, wrong verification number and expiry. Each must fail without key files.
- Repeat without manual cleanup and observe absence after five minutes. Sleep/worker termination can delay deletion.
- Stop, revoke and confirm acknowledgement. The next request must fail without files. Pair fresh endpoints before real keys.
Isolated Redis, subprocess and installer tests establish their tested layers. They do not prove actual GUI, published installation, provider access or intended ChatGPT discovery.