> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/moeru-ai/airi/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Runtime Overview

> WebSocket server runtime for AIRI integrations and module communication

## Overview

The `@proj-airi/server-runtime` package provides a WebSocket-based server runtime that enables real-time communication between AIRI modules, plugins, and clients. It handles authentication, routing, heartbeat management, and module registry synchronization.

## Installation

```bash theme={null}
npm install @proj-airi/server-runtime
```

## Key Features

* **WebSocket Communication**: Real-time bidirectional communication using H3 and crossws
* **Authentication**: Token-based authentication for secure connections
* **Module Registry**: Automatic discovery and synchronization of connected modules
* **Routing Middleware**: Flexible routing with policy-based access control
* **Heartbeat Management**: Automatic connection health monitoring
* **Event Broadcasting**: Intelligent event routing to appropriate peers

## Basic Usage

```typescript theme={null}
import { setupApp } from '@proj-airi/server-runtime'
import { listen } from 'listhen'

const { app, closeAllPeers } = setupApp({
  instanceId: 'my-server',
  auth: {
    token: 'your-secret-token'
  },
  logger: {
    app: { level: 'log', format: 'pretty' }
  }
})

// Start the server
const server = await listen(app, {
  port: 6121,
  hostname: 'localhost'
})

console.log(`Server running at ${server.url}`)
```

## Configuration

<ParamField path="instanceId" type="string" optional>
  Unique identifier for the server instance. Defaults to a generated nanoid.
</ParamField>

<ParamField path="auth.token" type="string" optional>
  Authentication token required for client connections. If not provided, authentication is disabled.
</ParamField>

<ParamField path="logger.app.level" type="LogLevelString" optional>
  Application log level: `'trace'`, `'debug'`, `'log'`, `'warn'`, `'error'`. Defaults to `'log'`.
</ParamField>

<ParamField path="logger.app.format" type="Format" optional>
  Log format: `'pretty'` or `'json'`. Defaults to `'pretty'`.
</ParamField>

<ParamField path="logger.websocket.level" type="LogLevelString" optional>
  WebSocket-specific log level. Defaults to app log level.
</ParamField>

<ParamField path="routing.middleware" type="RouteMiddleware[]" optional>
  Custom routing middleware functions for event filtering and routing decisions.
</ParamField>

<ParamField path="routing.allowBypass" type="boolean" optional>
  Allow devtools peers to bypass routing policies. Defaults to `true`.
</ParamField>

<ParamField path="routing.policy" type="RoutingPolicy" optional>
  Routing policy for plugin and label-based access control.
</ParamField>

<ParamField path="heartbeat.readTimeout" type="number" optional>
  Heartbeat timeout in milliseconds. Defaults to `60000` (60 seconds).
</ParamField>

<ParamField path="heartbeat.message" type="MessageHeartbeat | string" optional>
  Custom heartbeat message. Defaults to `MessageHeartbeat.Pong`.
</ParamField>

## Return Value

<ResponseField name="app" type="H3">
  H3 application instance with WebSocket handler configured.
</ResponseField>

<ResponseField name="closeAllPeers" type="() => void">
  Function to close all connected peer connections.
</ResponseField>

## Event Types

The server handles the following WebSocket event types:

* `transport:connection:heartbeat` - Connection health monitoring
* `module:authenticate` - Client authentication
* `module:announce` - Module registration and announcement
* `registry:modules:sync` - Module registry synchronization
* `ui:configure` - Module configuration from UI
* Custom events - Routed to appropriate peers based on routing rules

## Environment Variables

The server runtime supports the following environment variables:

* `SERVER_INSTANCE_ID` - Server instance identifier
* `AUTHENTICATION_TOKEN` - Default authentication token
* `LOG_LEVEL` - Default log level
* `LOG_FORMAT` - Default log format

## Architecture

The server runtime follows a peer-to-peer architecture where:

1. **Clients connect** via WebSocket to `/ws`
2. **Authentication** occurs if a token is configured
3. **Module announcement** registers the client in the module registry
4. **Events are routed** based on destinations and routing policies
5. **Heartbeats maintain** connection health

## Next Steps

<CardGroup cols={2}>
  <Card title="WebSocket Protocol" icon="network-wired" href="/api/server-runtime/websocket">
    Learn about the WebSocket protocol and message format
  </Card>

  <Card title="Event System" icon="bolt" href="/api/server-runtime/events">
    Explore the event system and routing mechanisms
  </Card>
</CardGroup>