What Is the Function of the packages/runtime-host Package in Apache Maka?

TLDR: The packages/runtime-host package implements the Maka Runtime Host, a lightweight local service that exposes your State Root and registered Projects to remote Maka clients over secure WebSocket transport.

The packages/runtime-host package is a core component of the Apache Maka repository that enables secure, remote access to local development environments. Running on Linux or macOS workstations, it transforms your machine into a persistent workspace host that remote Desktop, TUI, or CLI clients can connect to for executing tools and agents.

Core Responsibilities of the Runtime Host

Persistent Workspace Hosting

The Runtime Host maintains a State Root that stores all workspace data, including sessions, tool results, and configuration. As implemented in packages/runtime-host/src/runtime-host-service.ts, the host registers one or more Project roots under this State Root, allowing remote clients to browse and execute tools against them as if they were local.

Secure Transport Layer Implementation

Security is handled through multiple transport mechanisms defined in the source. The package listens on a loop-back WebSocket and optionally publishes it over TLS, SSH tunnels, or the experimental direct-peer transport using WebRTC/QUIC. The file packages/runtime-host/src/webrtc-stun-policy.ts contains the STUN server selection logic that enables direct peer connections when traditional endpoints are unavailable.

Service Lifecycle Management

The package automates host persistence through system-managed services. On Linux, it installs a systemd user service; on macOS, it uses a LaunchAgent. Both configurations auto-restart the host after upgrades or crashes. The CLI exposes commands like runtime-host service install, uninstall, status, and update to manage this lifecycle.

Peer-Mesh Discovery Coordination

For scenarios where TLS or SSH endpoints are inaccessible, the Runtime Host implements WebRTC STUN policy and mesh-relay logic. Administrators can configure custom STUN servers or disable public STUN usage entirely, as controlled through the configuration interfaces in packages/runtime-host/src/webrtc-stun-policy.ts.

Security Boundary Enforcement

The package enforces strict credential handling to prevent leakage via command-line arguments or JSON profiles. It supports an insecure plaintext mode only when explicitly enabled with the --allow-insecure-remote flag on trusted networks. Credential issuance and revocation are handled through runtime-host access issue and runtime-host access revoke commands.

Key Source Files and Architecture

The architecture is defined across several critical files:

• packages/runtime-host/package.json – Declares dependencies and CLI entry points.
• packages/runtime-host/tsconfig.json – TypeScript build configuration.
• packages/runtime-host/src/webrtc-stun-policy.ts – STUN policy implementation for direct-peer transport.
• packages/runtime-host/src/runtime-host-service.ts – Core service lifecycle logic.
• docs/runtime-host-remote-access.md – User-facing documentation for setup and security.

Practical Usage Examples

The following commands demonstrate typical Runtime Host operations performed on the host machine.

Install a persistent service with initial project registration:

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"

Add a Project for remote access:

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

Start the host with TLS encryption:

npm --workspace maka-agent exec -- \
    maka runtime-host serve \
    --root /srv/maka \
    --websocket-host 0.0.0.0 \
    --websocket-port 7443 \
    --tls-certificate /etc/maka/tls.crt \
    --tls-private-key /etc/maka/tls.key \
    --json

Issue one-time access credentials:

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>'

Configure the client-side profile:

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>'

Summary

• The packages/runtime-host package provides the Maka Runtime Host, enabling remote access to local workspaces.
• It exposes a State Root and registered Projects through secure WebSocket, TLS, SSH, or WebRTC/QUIC transports.
• The package manages its own lifecycle via systemd (Linux) or LaunchAgent (macOS) for automatic persistence.
• Security features include credential isolation, access revocation, and optional insecure mode for trusted networks.
• Key implementation files include runtime-host-service.ts for lifecycle logic and webrtc-stun-policy.ts for peer discovery.

Frequently Asked Questions

What operating systems does the packages/runtime-host package support?

The Runtime Host package supports Linux and macOS workstations. It leverages systemd user services on Linux and LaunchAgents on macOS to maintain persistent background operation. Windows support is not mentioned in the current source implementation.

How does the Runtime Host secure remote connections?

The host secures connections through TLS-encrypted WebSockets, SSH tunnels, or experimental direct-peer WebRTC/QUIC transport. Credentials are never exposed in command-line arguments; instead, the system uses temporary access tokens issued via runtime-host access issue that can be revoked when no longer needed.

Can I run the Runtime Host without installing a system service?

Yes, you can run the host ephemerally using the maka runtime-host serve command, which starts a WebSocket listener without installing systemd or LaunchAgent services. However, for production use, the persistent service installation via runtime-host setup is recommended to ensure automatic restarts after crashes or system reboots.

What is the purpose of the webrtc-stun-policy.ts file?

The webrtc-stun-policy.ts file implements the STUN (Session Traversal Utilities for NAT) server selection logic required for the experimental direct-peer transport. It enables the Runtime Host to establish direct connections between peers when traditional TLS or SSH endpoints are unavailable, while allowing administrators to configure custom STUN servers or disable public STUN usage for enhanced privacy.

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