# What Is `packages/runtime-host` in Apache Maka? Architecture and Implementation Guide

> Discover the Maka runtime host, a persistent service managing State Root and Projects. Learn how it securely connects clients to the execution engine via its WebSocket API.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-09-04

---

**The `packages/runtime-host` module implements the Runtime Host—a persistent, authoritative service that owns the State Root and Projects while exposing a WebSocket-based API to securely bridge desktop, TUI, and CLI clients with the execution engine.**

In the Apache Maka repository, `packages/runtime-host` serves as the architectural backbone that manages durable workspace state and coordinates remote access. This module runs as a long-lived daemon—typically managed by systemd on Linux or LaunchAgent on macOS—to ensure that session history, project metadata, and credential policies remain available independent of any particular client connection.

## Architectural Position in the Maka Stack

The Runtime Host occupies the critical middle layer in Maka's three-tier architecture, acting as the sole authority for resource access and state persistence.

### The Layered Architecture

- **Client Layer (Desktop / TUI / CLI):** Handles UI rendering, command parsing, and local credential storage. These clients communicate with the Runtime Host over TLS, SSH, or experimental direct-peer transports.
- **Runtime Host (`packages/runtime-host`):** Owns the **State Root** (e.g., `~/.maka/runtime-host`), registers **Projects**, and exposes a WebSocket API that coordinates sessions, resources, and plugins. It enforces access policies and manages the lifecycle of all execution requests.
- **Execution Engine (Worker Processes):** Performs actual prompt execution, model inference, and filesystem I/O. The Runtime Host invokes workers through internal coordinators such as `runtime-policy-coordinator` and `session-turn-access-request-coordinator`.

## Core Responsibilities of the Runtime Host

### State Root Ownership and Persistence

The Runtime Host maintains exclusive read/write access to the **State Root**, the canonical directory containing workspace metadata, session transcripts, and plugin composition graphs. Located by default at `~/.maka/runtime-host`, this directory persists across client reconnections and system reboots, ensuring continuity for long-running projects.

### Project Registration and Management

As the authority for host resources, the Runtime Host maintains a registry of **Projects** and enforces a *project-root* allowlist that restricts which directories remote clients may browse. Administrators register projects via CLI commands, and the host validates all filesystem access against this registry.

### Secure Transport and API Exposure

`packages/runtime-host` abstracts multiple transport protocols behind a unified WebSocket API:

- **Loopback WebSocket:** Default local communication on loopback interface.
- **TLS and SSH Tunnels:** Encrypted remote access with mandatory certificate validation.
- **Direct-Peer Transport:** Experimental QUIC/WebRTC connectivity implemented in [`packages/runtime-host/src/transport/peer-native.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/peer-native.ts).

The host never silently downgrades encrypted connections to plaintext; operators must explicitly enable insecure mode with `--allow-insecure-remote` for specific debugging scenarios.

### Policy Enforcement and Access Control

The `runtime-policy-coordinator` (defined in [`packages/runtime-host/src/server/runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts)) validates all incoming requests. It issues per-client credentials through the `runtime-host access issue` command, verifies these credentials on every connection, and enforces the project-root allowlist to prevent unauthorized directory traversal.

### Session Coordination and Resource Management

The Runtime Host hosts a suite of specialized coordinators that serialize access to shared resources:

- **`turn-control-coordinator`:** Manages execution turns to prevent conflicting operations.
- **`session-continuity-coordinator`:** Ensures session state survives client disconnections.
- **`plugin-platform-coordinator`:** Handles dynamic loading and isolation of plugins.

These components work together in [`packages/runtime-host/src/server/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/index.ts), the entry point that initializes the WebSocket listener and starts the host service.

## Key Source Files and Implementation Details

| File Path | Purpose |
|-----------|---------|
| [`packages/runtime-host/src/server/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/index.ts) | Entry point that creates the WebSocket listener, instantiates coordinators, and starts the persistent host service. |
| [`packages/runtime-host/src/server/runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts) | Central policy engine for credential validation and project-root enforcement. |
| [`packages/runtime-host/src/server/host-resource-probe-main.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-resource-probe-main.ts) | Diagnostic utility for probing host resource availability and health status. |
| [`packages/runtime-host/src/transport/websocket-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/websocket-transport.ts) | WebSocket implementation used by TLS and SSH transport layers. |
| [`packages/runtime-host/src/transport/peer-native.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/peer-native.ts) | Native implementation of the experimental direct-peer (QUIC/WebRTC) transport. |
| [`docs/runtime-host-remote-access.md`](https://github.com/apache/maka/blob/main/docs/runtime-host-remote-access.md) | Official documentation covering setup procedures, transport configuration, and security hardening. |

## Deploying and Configuring the Runtime Host

### Install and Initialize a Persistent Host

The following command installs the Maka package, initializes the State Root at `~/.maka/runtime-host`, registers a principal identity, and configures the service to auto-start via systemd or LaunchAgent:

```bash
npx --yes --package maka-agent@latest \
    maka runtime-host setup \
    --principal my-desktop \
    --preset desktop-client \
    --root "$HOME/.maka/runtime-host" \
    --project-root "projects=$HOME/Projects"

```

### Register a Project on the Host

```bash
npm --workspace maka-agent exec -- \
    maka runtime-host project add /srv/projects/example \
    --root /srv/maka

```

### Issue Client Credentials

Generate a short-lived credential that the client must store in `MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL`:

```bash
npm --workspace maka-agent exec -- \
    maka runtime-host access issue \
    --root /srv/maka \
    --principal my-desktop \
    --preset desktop-client

```

### Enable Experimental Direct-Peer Transport

```bash
maka runtime-host service peer enable \
    --expected-service-id '<serviceId>' \
    --expected-root-path '<rootPath>' \
    --expected-root-id '<rootId>'

```

### Connect a CLI Client to a TLS-Protected Host

```bash
export MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL='<credential>'

maka runtime-host profile set \
    --id office \
    --name Office \
    --tls-url wss://runtime.example.com:7443/runtime-host \
    --expected-root '<rootId>'

maka --host office --project '<projectId>' run "Summarize this project"

```

### Revoke Compromised Credentials

```bash
maka runtime-host access revoke \
    --root /srv/maka \
    --credential <credentialId>

```

## Summary

- **`packages/runtime-host` implements the central authority** that manages State Root persistence and Project registration in Apache Maka.
- **It operates as a persistent system service**, independent of client applications, ensuring workspace continuity across sessions.
- **The module enforces strict security boundaries** through TLS/SSH transport, credential issuance via `runtime-policy-coordinator`, and project-root allowlists.
- **It bridges client frontends to execution workers** through a WebSocket-based API and internal coordinators that manage turn control, session continuity, and plugin loading.
- **Configuration and deployment** utilize CLI commands such as `runtime-host setup`, `project add`, and `access issue` to initialize and secure the host environment.

## Frequently Asked Questions

### What distinguishes the Runtime Host from the Execution Engine in Apache Maka?

The **Runtime Host** (`packages/runtime-host`) is a long-running service that manages state persistence, security policies, and client connections, while the **Execution Engine** consists of ephemeral worker processes that actually run prompts and perform I/O. The Runtime Host invokes workers through coordinators like `session-turn-access-request-coordinator` but does not execute user code directly.

### How does `packages/runtime-host` secure remote client connections?

The module mandates encrypted transports by default—either TLS-wrapped WebSockets or SSH tunnels—and validates all connections through the `runtime-policy-coordinator`. It issues cryptographically secure credentials via `maka runtime-host access issue` and enforces a project-root allowlist to limit filesystem exposure. Plaintext mode requires explicit opt-in via `--allow-insecure-remote`.

### Where does the Runtime Host store session history and workspace metadata?

All workspace metadata, session transcripts, and plugin composition graphs reside in the **State Root**, typically located at `~/.maka/runtime-host` for user installations or a custom path specified via `--root`. This directory is owned exclusively by the Runtime Host process and persists across system restarts.

### Can the Runtime Host operate without any client connected?

Yes. The Runtime Host runs as a persistent background service (systemd user service on Linux, LaunchAgent on macOS) and maintains active state management even when no Desktop, TUI, or CLI clients are connected. Clients connect opportunistically to an already-running host, enabling asynchronous session continuity and remote execution capabilities.