halyn 0.3.0

Halyn — NRP control plane with domain-scoped authorization.

Halyn

The AI control plane. Connect any device to any LLM.

12 drivers · 5 autonomy levels · tamper-evident audit · shield rules

Website · Quickstart · Use Cases · Docs

---

The Problem

AI is moving into the physical world. Robots, drones, smart homes, factories, vehicles. But there's no universal way for an LLM to safely control hardware.

MCP connects LLMs to software APIs. Halyn connects LLMs to everything else — servers, sensors, robots, serial ports, browsers, Docker containers. With safety built in at the protocol level.

Quickstart

pip install halyn

Monitor a server in 5 lines:

from halyn import ControlPlane, SSHDriver

cp = ControlPlane()
cp.connect(SSHDriver("192.168.1.10", "admin"))
print(cp.observe())  # → {"cpu": 23.4, "mem": 67.2, "disk": 45.1, ...}

Control a Raspberry Pi GPIO:

from halyn import ControlPlane, SSHDriver

cp = ControlPlane()
cp.connect(SSHDriver("raspberrypi.local", "pi"))

# Add a safety rule: never touch GPIO 4 (connected to emergency stop)
cp.shield("deny gpio write 4")

cp.act("gpio write 17 high")   # ✓ turns on LED
cp.act("gpio write 4 low")     # ✗ blocked by shield rule

Let Claude control your home lab:

from halyn import ControlPlane, SSHDriver, Autonomy

cp = ControlPlane(autonomy=Autonomy.SUPERVISED)  # AI proposes, human approves
cp.connect(SSHDriver("homelab.local", "admin"))

# Shield: read-only on production, full access on staging
cp.shield("deny * write /prod/*")
cp.shield("allow * * /staging/*")

# AI can now observe and propose actions
# Human gets a prompt before anything executes

12 Drivers

Driver	What It Connects	Example
SSHDriver	Any Linux/Mac server	Monitor servers, deploy code
HTTPDriver	REST APIs, webhooks	Control smart home APIs
WebSocketDriver	Real-time streams	Live sensor data
SerialDriver	Arduino, Raspberry Pi, PLCs	Read sensors, control actuators
MQTTDriver	IoT networks	Smart agriculture, building automation
OPCUADriver	Industrial machines (Industry 4.0)	CNC, SCADA, factory equipment
ROS2Driver	Robots (ROS ecosystem)	Robot arms, mobile robots, drones
DDSDriver	Real-time distributed systems	Autonomous vehicles, defense
DockerDriver	Containers and orchestration	Scale services, manage deployments
BrowserDriver	Web automation	Fill forms, scrape data, test UIs
UnitreeDriver	Unitree robots	Go2, B2, H1 quadrupeds and humanoids
SocketDriver	Raw TCP/UDP	Custom hardware, legacy systems

5 Autonomy Levels

Level	Name	Who Decides	Use Case
0	Manual	Human does everything	Learning, debugging
1	Advisory	AI suggests, human executes	Critical systems
2	Supervised	AI executes, human approves first	Production ops
3	Monitored	AI executes freely, human can intervene	Routine tasks
4	Autonomous	AI decides within shield rules	Fully automated systems

Shield Rules — Safety as Physics

Shield rules aren't guidelines. They're constraints enforced at the protocol level. Your AI physically cannot violate them, regardless of its instructions.

# Industrial safety
cp.shield("deny actuator write pressure > 150")   # never exceed 150 PSI
cp.shield("deny motor write speed > 3000")         # RPM limit
cp.shield("require human_approval for emergency_stop disable")

# Data safety
cp.shield("deny * read /etc/shadow")
cp.shield("deny * write /prod/database/*")
cp.shield("deny * delete *")  # read-only mode

# Rate limiting
cp.shield("limit actions 10/minute")

Audit Chain

Every action Halyn executes is recorded in a tamper-evident SHA-256 chain. Nothing can be altered or deleted.

# View the audit trail
for entry in cp.audit.chain():
    print(f"{entry.timestamp} | {entry.action} | {entry.result} | {entry.hash[:12]}")

# 2026-03-17T01:30:00 | observe cpu     | 23.4%      | a3f8c9d1e2b4
# 2026-03-17T01:30:01 | act restart nginx| success    | 7b2e4f6a8c0d
# 2026-03-17T01:30:02 | observe cpu     | 12.1%      | e5d7c9b1a3f8

Perfect for compliance (SOC2, ISO 27001, GDPR audit trails).

Use Cases

🏭 Smart Factory

Connect AI to your factory floor. OPC-UA driver reads machine data. Shield rules prevent dangerous operations. Audit chain provides compliance trail.

cp = ControlPlane(autonomy=Autonomy.MONITORED)
cp.connect(OPCUADriver("opc.tcp://plc-01:4840"))
cp.shield("deny * write temperature > 200")
cp.shield("deny * write pressure > 150")

# AI monitors machines, optimizes parameters within safe bounds
# Every adjustment is audited

🌱 Precision Agriculture

MQTT sensors across your field report soil moisture, temperature, weather. AI decides when to irrigate, which zones need attention.

cp = ControlPlane()
cp.connect(MQTTDriver("mqtt://field-gateway:1883"))
cp.shield("limit irrigation 3/day")  # prevent overwatering
cp.shield("deny irrigation if wind > 30")  # no sprinklers in wind

data = cp.observe()  # reads all sensors
# AI analyzes and triggers irrigation for dry zones

🏥 Patient Monitoring

Serial connection to medical devices. AI watches vitals 24/7, alerts staff immediately when something changes. Shield rules ensure the AI can never modify device settings.

cp = ControlPlane(autonomy=Autonomy.ADVISORY)  # AI advises only
cp.connect(SerialDriver("/dev/ttyUSB0", baudrate=9600))
cp.shield("deny * write *")  # read-only — AI cannot control the device

vitals = cp.observe()  # heart rate, SpO2, blood pressure
# AI detects anomaly → alerts nurse station

🤖 Robot Fleet

ROS2 driver connects to any robot in the ROS ecosystem. Shield rules define the workspace. Consent protocol ensures robots agree before coordinating.

cp = ControlPlane()
cp.connect(ROS2Driver("robot-arm-01"))
cp.connect(ROS2Driver("robot-arm-02"))

cp.shield("deny movement outside workspace_bounds")
cp.shield("deny force > 50N")  # collaborative robot limits

# Consent: robots negotiate shared workspace access
cp.consent("robot-arm-01", "robot-arm-02", scope="shared_zone_A")

🏠 Smart Home

Connect every device in your home. Your AI assistant can control lights, thermostat, locks — but shield rules ensure it can never unlock doors at night or set the thermostat below 15°C.

cp = ControlPlane()
cp.connect(MQTTDriver("mqtt://home-hub:1883"))

cp.shield("deny lock unlock between 23:00-06:00")
cp.shield("deny thermostat write < 15")
cp.shield("deny * * camera")  # AI has no camera access

cp.act("lights living_room dim 40%")

🎓 Education

Students learn AI-hardware interaction in 10 lines. Connect an Arduino, read a temperature sensor, make an LED blink based on AI decisions.

from halyn import ControlPlane, SerialDriver

cp = ControlPlane()
cp.connect(SerialDriver("/dev/ttyACM0"))

temp = cp.observe()["temperature"]
if temp > 30:
    cp.act("led on")   # too hot → warning LED
else:
    cp.act("led off")

Built on NRP

Halyn implements NRP (Node Reach Protocol) — 6 primitives that define how AI talks to hardware:

Primitive	Purpose
Manifest	"I am" — device declares its identity and capabilities
Observe	"I see" — read state without side effects
Act	"I do" — execute an action on the device
Shield	"I cannot" — enforceable constraints
Audit	"I did" — tamper-evident action log
Consent	"We agree" — mutual permission negotiation

Contributing

See CONTRIBUTING.md. We especially welcome new drivers and shield rule patterns.

License

MIT — use it anywhere, for anything.

---

halyn.dev · [e-mail] · © 2026 Elmadani SALKA