Deep Dive into Kyronix Bi-directional WebSocket Architecture & Security

# Deep Dive into Kyronix Bi-directional WebSocket Architecture & Security

Running AI agents that modify your local filesystem or execute shell commands presents a fundamental architectural dilemma: **How can a cloud-hosted AI model orchestrate local machine actions safely, instantly, and without forcing developers to expose open HTTP ports or configure risky Ngrok tunnels?**

Kyronix solves this with a **Decoupled Bi-Directional WebSocket Architecture**. In this system, Kyronix Cloud handles intelligence, context compilation, and planning, while `@kyronixai/executer` runs on your workstation as a secure, local client daemon.

---

Architectural Breakdown: Cloud Intelligence vs. Local Client

Traditional agent frameworks bundle LLM prompting, model API keys, and local filesystem access into a single monolith script. This creates severe security risks and scalability bottlenecks:

1Monolithic Agent Approach (Risky & Hard to Scale)
2┌──────────────────────────────────────────────────────────┐
3│ Local Workstation                                        │
4│  ├── Stores OpenAI/Claude API Keys in plaintext          │
5│  ├── Performs Heavy LLM Token Context Compilation        │
6│  └── Executes Shell & Filesystem Directly                │
7└──────────────────────────────────────────────────────────┘

Kyronix decouples these responsibilities into two distinct, highly specialized layers:

1Kyronix Decoupled Architecture
2┌─────────────────────────┐              ┌──────────────────────────┐
3│ Developer Workstation   │              │ Kyronix Cloud Platform   │
4│                         │              │                          │
5│ @kyronixai/executer     │ Outbound TCP │ Kyronix Cloud API        │
6│  ├── No Model Keys      │─────────────►│  ├── Groq Llama 70B      │
7│  ├── Local Tools        │ ws://cloud/ws│  ├── Context Compiler    │
8│  └── Path Sandbox       │◄─────────────│  └── KML Engine          │
9└─────────────────────────┘ Streaming KML└──────────────────────────┘

---

The Outbound WebSocket Tunnel Protocol (`executeKmlOverWs`)

To eliminate public port forwarding requirements, `@kyronixai/executer` establishes an **outbound TCP WebSocket connection** to the Kyronix Relay server.

Why Outbound Connections Matter: 1. **Firewall & NAT Traversal**: Outbound TCP connections on standard ports (443/80) pass through corporate firewalls, NAT routers, and VPNs effortlessly. 2. **Zero Inbound Attack Surface**: Because your local workstation opens no listening HTTP ports, attackers cannot scan or probe your machine for vulnerabilities. 3. **Instant Push Messaging**: The server pushes KML action graphs to the client instantly over the open socket without REST polling overhead.

---

Sequence Breakdown: A Complete Execution Loop

Let's trace what happens when your backend triggers an agent run over the WebSocket tunnel:

1// server.ts - Your Application Backend
2import { Kyronix } from '@kyronixai/runtime';

const ws = new WebSocket('wss://kyronix.harshitnakrani.me/ws'); const kyronix = new Kyronix({ apiKey: process.env.KYRONIX_API_KEY!, ws });

// Dispatch prompt to Kyronix Cloud and execute KML over WebSocket tunnel const runResult = await kyronix.run({ agent: 'coding', input: 'Create src/index.ts' }); const executionResults = await kyronix.executeKmlOverWs(runResult.response); ```

Detailed Message Sequence:

1. **Prompt Dispatch**: Your backend calls `kyronix.run()`, sending the prompt to Kyronix Cloud. 2. **Context Compilation & KML Generation**: Kyronix Cloud ingests session history, injects active project file context, and runs model reasoning to generate a KML plan. 3. **KML Request Frame (`kml_request`)**: Kyronix Cloud pushes a structured JSON payload to the connected `@kyronixai/executer` over WebSockets: ```json { "type": "kml_request", "executionId": "exec_88192a", "kmlResponse": "<tool name="write_file"><path>src/index.ts</path><content>console.log('Hello');</content></tool>" } ``` 4. **Local Execution & Sandbox Inspection**: The local `@kyronixai/executer` parses the KML, verifies path safety via `Sandbox.isPathSafe()`, and writes the file locally. 5. **KML Result Frame (`kml_result`)**: Results are pushed back to the server: ```json { "type": "kml_result", "executionId": "exec_88192a", "results": [ { "tool": "write_file", "args": { "path": "/app/src/index.ts" }, "result": { "success": true } } ] } ```

---

Security Model: Local Sandboxing & Permission Policies

Running LLM-generated commands on local host operating systems requires rigorous safety controls. `@kyronixai/executer` implements a multi-tier security model:

1. Path Traversal Prevention (`Sandbox.isPathSafe`) Before any file operation (`read_file`, `write_file`, `delete_file`, `move_file`) is dispatched, the executer resolves the target path relative to the active workspace directory. If an agent attempts path traversal (`../../../../etc/passwd`), the sandbox blocks execution immediately and throws a `SecurityError`.

2. Policy Enforcements (`SAFE_POLICIES` vs `ROOT_POLICIES`) - **`SAFE_POLICIES` (Default)**: Restricts tool actions strictly to designated workspace directories, blocks destructive system commands, and requires user approval for high-risk operations. - **`ROOT_POLICIES`**: Unlocks full root system access for containerized sandboxes or isolated Docker environments.

---

Summary

The Kyronix WebSocket architecture delivers **uncompromising performance with enterprise-grade security**—giving developers the speed of real-time cloud planning with complete peace of mind over local client execution.