@kyronixai/executer

The execution engine for Kyronix.

The @kyronixai/executer package is the client-side execution layer of the Kyronix Platform. It receives execution instructions from the Kyronix Runtime, safely executes them in the local environment, and streams the results back to the Kyronix Cloud.

It is designed to work alongside @kyronixai/runtime and is responsible for interacting with the host operating system.

Installation

npm install @kyronixai/executer

or

pnpm add @kyronixai/executer

or

yarn add @kyronixai/executer

Requirements

• Node.js 20+
• A running Kyronix Runtime session

This package is not intended to be used directly. It works in conjunction with @kyronixai/runtime.

What does it do?

The executer is responsible for executing agent actions inside the local environment.

It provides execution for:

• Terminal Commands
• File Operations
• Directory Operations
• Browser Automation
• Git Operations
• HTTP Requests
• Custom Tools

The executer never performs reasoning or planning.

All decisions are made by the Kyronix Runtime.

Architecture

                Kyronix Cloud
                       │
              Execution Instructions
                       │
                Secure WebSocket
                       │
        @kyronixai/executer
                       │
       ┌───────────────┼────────────────┐
       │               │                │
   Terminal       File System       Browser
       │               │                │
       └───────────────┼────────────────┘
                       │
                Execution Results
                       │
                Kyronix Cloud

Quick Start

import { KyronixExecuter } from "@kyronixai/executer";

const executer = new KyronixExecuter({
  sessionId: process.env.KYRONIX_SESSION_ID!,
  token: process.env.KYRONIX_EXECUTOR_TOKEN!,
});

await executer.connect();

The executer automatically:

• Connects to the Kyronix Platform
• Receives execution instructions
• Executes supported tools
• Returns execution results
• Maintains the execution session

Supported Executors

Terminal

Execute shell commands.

Examples:

• npm
• pnpm
• yarn
• git
• python
• node

File System

Supports:

• Read File
• Write File
• Delete File
• Create Directory
• Move File
• Copy File
• List Directory

Browser

Supports browser automation including:

• Navigation
• Clicking
• Typing
• Screenshots
• DOM Queries

Git

Supports common Git operations.

Examples:

• Clone
• Commit
• Checkout
• Branch
• Status
• Push
• Pull

HTTP

Execute HTTP requests.

Supports:

• GET
• POST
• PUT
• PATCH
• DELETE

Security

The executer executes operations only for authenticated runtime sessions.

Every execution request is:

• Authenticated
• Authorized
• Session scoped

No execution is accepted without a valid Kyronix Runtime session.

Custom Executors & Custom Agent Tools

Register custom tool handlers on your local machine to handle custom agent tools configured in the Kyronix Dashboard:

import { KyronixExecuter } from "@kyronixai/executer";

const executer = new KyronixExecuter();

// Register a custom tool matching your Custom Agent's schema
executer.register("web_search", async (args) => {
  const query = args.searchString || args.query;
  console.log(`Executing custom web_search tool for query: ${query}`);
  
  return {
    results: [
      { title: "Elon Musk - Biography", url: "https://example.com/musk" }
    ]
  };
});

When a custom agent streams XML tool commands (<tool name="web_search"><query>...</query></tool>), KyronixExecuter automatically parses the AST, extracts arguments, and dispatches the execution to your custom handler.

Relationship with @kyronixai/runtime

Your Backend
      │
      ▼
@kyronixai/runtime
      │
      ▼
Kyronix Platform
      │
      ▼
@kyronixai/executer
      │
      ▼
Local Environment

The runtime handles:

• Authentication
• Sessions
• AI Communication
• Planning
• Memory
• Context Management
• Agent Lifecycle

The executer handles:

• Terminal
• Files
• Browser
• Git
• HTTP
• Custom Tools

Together they provide a complete agent execution platform.

Configuration

const executer = new KyronixExecuter({
  sessionId: "...",
  token: "...",
  reconnect: true,
  heartbeatInterval: 30000,
});

API

Initialize

new KyronixExecuter(config)

Creates a new executer instance.

Connect

await executer.connect()

Connects the executer to the Kyronix Platform.

Disconnect

await executer.disconnect()

Gracefully closes the connection.

Register

executer.register(name, handler)

Registers a custom executer.

Events

executer.on("connected", () => {});

executer.on("disconnected", () => {});

executer.on("execution:start", () => {});

executer.on("execution:complete", () => {});

executer.on("error", () => {});

Documentation

Complete documentation is available at:

https://kyronix.harshitnakrani.me

License

MIT

Built with ❤️ by the Kyronix Team.