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

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.

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) 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, 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	Entry point that creates the WebSocket listener, instantiates coordinators, and starts the persistent host service.
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	Diagnostic utility for probing host resource availability and health status.
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	Native implementation of the experimental direct-peer (QUIC/WebRTC) transport.
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:

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

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:

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

Enable Experimental Direct-Peer Transport

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

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

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}