halyn 2.1.0

Halyn — The governance layer for AI agents. Every action intercepted. Every decision auditable.

Halyn

The governance layer for AI agents.

Every action intercepted. Every decision auditable. The AI cannot bypass it.

Website · Why Halyn · Install · Architecture · Protocols

---

Why Halyn

AI agents — Claude, GPT, Gemini, local models — act on your machine. They read files, send emails, control browsers, call APIs. With no independent proof of what happened.

Halyn is the independent layer that sits between any AI agent and your system.

Claude / GPT / Gemini / Ollama / Any agent
                │
                ▼
    ┌─────────────────────────────┐
    │       HALYN LAYER           │  ← runs locally, out of agent reach
    │                             │
    │  • Identity   — who is acting?          │
    │  • Consent    — was it approved?        │
    │  • Audit      — SHA-256 chain proof     │
    │  • Shield     — what can it NOT do?     │
    │  • Watchdog   — integrity monitoring    │
    └─────────────────────────────┘
                │
                ▼
        Your machine · Your files · Your system

Every action produces a cryptographic proof stored locally. Not in the cloud. Not at Anthropic. On your machine.

---

Install

pip install halyn
halyn serve

Opens the dashboard at http://localhost:7420. Nothing leaves your machine.

# Or with curl
curl -fsSL https://halyn.dev/install | bash

The install script tells you exactly what it will do before doing anything.

---

Quick Start

from halyn import ControlPlane

# Start the governance layer
gov = ControlPlane()
gov.serve()  # dashboard at localhost:7420

# Register an agent
agent = gov.register_agent(
    name="claude-cowork",
    provider="anthropic",
    autonomy_level=2,  # executor — reversible actions only
)

# Every agent action is intercepted and recorded
result = agent.act("read_file", "/docs/contract.pdf")
print(result.proof)    # sha256:a3f2e1...
print(result.allowed)  # True

---

Architecture

Halyn intercepts at three independent layers simultaneously:

Layer 1 — API Proxy

All LLM API calls (Claude, GPT, Gemini) pass through a local proxy on 127.0.0.1.
Intent is read before transmission. Shield rules apply before the request reaches the provider.
Implemented via iptables REDIRECT — kernel-level, not a library hook.

Layer 2 — Filesystem Hooks

inotify (Linux) / FSEvents (macOS) / ReadDirectoryChanges (Windows).
Every file access by an agent process is captured before execution, at the VFS layer.
LD_PRELOAD cannot bypass this — inotify fires in kernel space regardless.

Layer 3 — Process Isolation + eBPF

Halyn runs as a separate system user. Agents cannot read or write its audit database.
On Linux ≥5.8: eBPF programs are pinned to /sys/fs/bpf/halyn/ and monitor all syscalls.
Audit chain is SHA-256 with chained hashes, AES-256 encrypted at rest.

Layer 4 — Browser Guard (optional)

Chrome Enterprise Policy extension intercepts all CDP calls, DOM mutations, XHR, and fetch.
Deployed via /etc/opt/chrome/policies/managed/halyn.json — the agent cannot uninstall it.

---

Autonomy Levels

Level	Name	What the agent can do
0	Observer	Read-only access. No mutations.
1	Assistant	Suggests actions. Human executes.
2	Executor	Executes reversible actions.
3	Delegated	Executes with post-hoc audit.
4	Autonomous	Full autonomy. Use with extreme caution.

---

Supported Agents

Agent	Type	Integration
Claude (Anthropic)	Cloud	Proxy + MCP
GPT-4o / o3 (OpenAI)	Cloud	Proxy
Gemini (Google)	Cloud	Proxy
Ollama	Local	Direct
LM Studio	Local	Direct
Jan.ai	Local	Direct
OpenClaw	Agentic	Interceptor
Any MCP agent	Any	MCP server

---

Protocols

Halyn implements two open protocols:

AAP — Agent Accountability Protocol

The accountability layer MCP and A2A don't have.
Four primitives: Identity, Provenance, Authorization, Audit.
Spec: github.com/halyndev/aap · License: MIT

NRP — Node Reach Protocol

Safety standard for agents in physical and connected systems.
Six rules: Manifest, Observe, Act, Shield, Audit, Consent.
Spec: github.com/halyndev/nrprotocol · License: MIT

---

Dashboard

The local dashboard at http://localhost:7420 provides:

• Live feed — every agent action in real time, in plain language
• Agents — who is active, at what autonomy level, how to pause or stop
• Audit chain — cryptographic proof of every action since install
• Rules — configure what each agent can and cannot do
• Protocols — connected devices and integrations
• Insights — patterns, blocked actions, anomalies

The dashboard process runs under a separate system user. Agents cannot kill, read, or modify it.

---

Security Honest Statement

Halyn does not claim bypassing is impossible.
Halyn claims: every bypass attempt leaves a proven trace you see first.

Known limitations are documented in SECURITY.md.
Report vulnerabilities to [e-mail] — we respond within 24 hours.

---

Contributing

See CONTRIBUTING.md.

---

License

BSL-1.1 — Business Source License 1.1

• Free for personal use, research, and education
• Commercial use requires a license — [e-mail]
• Change date: 2029-03-25 → becomes MIT automatically

Protocol specs (AAP, NRP) are MIT and always will be.

---

Author: Elmadani SALKA · [e-mail] · halyn.dev