Documentation Index
Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Harness
Why the Expanded Being Needs a Gate
The Problem
Kernel CLI gives AI full access to the operating system. It can press any button
in any app, type arbitrary text, run AppleScript, read Safari history, take
screenshots, and kill processes.
Without a gate, an AI agent can do all of this the moment it is given access to
the terminal. There is no “are you sure?” There is no permission dialog. The
command runs and the action happens.
This is brave mode — raw capability with no control layer.
$ kernel-cli --help
┌──────────────────────────────────────────────────────────────────────────────┐
│ ⚠ BRAVE MODE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ You are using kernel-cli directly. There is no permission gate. │
│ Every command executes immediately — including write operations │
│ like ax-press, type, click, key, and script. │
│ │
│ This means: │
│ • AI agents can press any button in any app │
│ • AI agents can type arbitrary text │
│ • AI agents can run AppleScript with full OS access │
│ • No OTP, no token, no audit trail │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
The Solution: Three Tiers
NIIA embeds kernel-cli as a Rust library crate and wraps it with a permission
layer. The same code runs, but access is gated.
┌─────────────────────────────────────────────────────────────────────────────────┐
│ OPEN — always allowed (structure only, no content) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ niia observe windows List window titles and positions │
│ niia observe process Running processes and CPU/memory │
│ niia observe permissions macOS permission status │
│ niia observe network Network interfaces and DNS │
│ niia observe lsof :3000 Port and process mapping │
│ niia observe search "term" Spotlight file name search │
│ │
│ These expose structure — window list, process table, network config. │
│ No personal content. No screen content. Always safe. │
│ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ GATED — requires OTP unlock (exposes screen content / personal data) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ niia observe snapshot Windows + accessibility tree + clipboard │
│ niia observe ax-tree Full accessibility tree of any app │
│ niia observe capture Screenshot (full screen or region) │
│ niia observe query safari Browser history (SQLite) │
│ niia observe query notes Apple Notes content │
│ niia observe defaults App preferences and settings │
│ niia observe log System logs │
│ │
│ These expose what is ON the screen — text fields, passwords, personal notes. │
│ Requires the same OTP token as control commands. │
│ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ LOCKED — requires OTP unlock (writes to OS) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ niia control ax-press "OK" Press button by accessibility title │
│ niia control type "hello" Type text into focused element │
│ niia control click 500 300 Click at coordinates │
│ niia control key "cmd+s" Press key combination │
│ niia control script "..." Run AppleScript/JXA │
│ niia control open "url://..." Open URL scheme │
│ niia control kill 1234 Kill process │
│ │
│ These change the state of the operating system. │
│ The most sensitive tier. Requires OTP unlock. │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
The OTP Gate
The gate between locked and unlocked is an email OTP verified by the server,
returning an Ed25519 signed token that the binary verifies offline.
Why OTP Is the Only Human-Proof Layer
Things AI can do: Things AI cannot do:
✅ Write code ❌ Read your email inbox
✅ Run terminal commands ❌ Receive OTP on your phone
✅ Call APIs ❌ Access a separate device
✅ Write files to disk ❌ Forge Ed25519 signatures
✅ Execute shell scripts
The Flow
$ niia control unlock --scope full --duration 1h
1. niia reads stored email from keychain
2. Server sends OTP to email
3. Human reads email, enters 6-digit code
4. Server verifies OTP, returns JWT
5. niia requests signed control token from gateway
→ Gateway verifies JWT
→ Gateway signs { scope, exp, device_id } with Ed25519 private key
→ Returns signed token
6. niia saves token locally
7. All subsequent observe-gated and control commands check this token
→ Ed25519 signature verified OFFLINE (public key embedded in binary)
→ Expiry checked against current time
→ No network needed after unlock
Why Ed25519 Instead of Just JWT
The OTP verify step returns a standard JWT. Why not use that directly?
JWT only:
Every niia control command → network call to verify → slow, offline impossible
Ed25519 token:
Every niia control command → read local file → verify signature with
embedded public key → instant, works offline, works on airplane
Separate Keys
The kernel control signing key is separate from all other signing keys:
The kernel control signing key is a separate Ed25519 keypair from all other
signing infrastructure. Different purpose, different key. If one is compromised,
the other is unaffected.
What AI Cannot Do
Tested and verified:
AI attempt: echo "fake" > ~/.niia/control-token
Result: ❌ "Invalid token format (not signed JSON). Token may be forged."
AI attempt: echo '{"data":"...","signature":"AAAA..."}' > ~/.niia/control-token
Result: ❌ "Signature verification FAILED — token may be forged or tampered."
AI attempt: Construct valid JSON with correct format but wrong signature
Result: ❌ "Signature verification FAILED"
AI attempt: Call niia control unlock (requires OTP code)
Result: ❌ Cannot enter OTP — code is in human's email
The Pattern: OTP Gate as Primitive
The OTP flow is implemented as a reusable module. One function, any purpose — pass a purpose string, get back a verified JWT:
otp_gate::prompt("kernel-control") → verified JWT
otp_gate::prompt("remote-admin") → verified JWT
otp_gate::prompt("git-force-push") → verified JWT
purpose string is sent as app_code to the OTP server. Different purposes
can have different rate limits, different token lifetimes, different audit
requirements — all without changing the client code.
Any future feature that needs human proof can use this gate:
kernel control + OTP gate = harnessed OS control
remote admin + OTP gate = harnessed remote access
destructive git + OTP gate = harnessed force-push
payment action + OTP gate = harnessed transaction
Brave Mode vs Harnessed Mode
kernel-cli (brave):
→ No restrictions. Full OS access. Immediate execution.
→ For: developers who know what they're doing, local testing, scripts.
→ Warning displayed on every --help invocation.
niia observe/control (harnessed):
→ 3-tier permission. OTP required for sensitive operations.
→ For: AI agents, production use, shared machines, auditable access.
→ The same kernel code runs — but only after human proof.
