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

> Discover the Maka Runtime Host package in Apache Maka. This vital component enables remote Maka clients to access your State Root and Projects via secure WebSocket.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime-host/package.json) – Declares dependencies and CLI entry points.
- [`packages/runtime-host/tsconfig.json`](https://github.com/apache/maka/blob/main/packages/runtime-host/tsconfig.json) – TypeScript build configuration.
- [`packages/runtime-host/src/webrtc-stun-policy.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/webrtc-stun-policy.ts) – STUN policy implementation for direct-peer transport.
- [`packages/runtime-host/src/runtime-host-service.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/runtime-host-service.ts) – Core service lifecycle logic.
- [`docs/runtime-host-remote-access.md`](https://github.com/apache/maka/blob/main/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:

```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"

```

Add a Project for remote access:

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

```

Start the host with TLS encryption:

```bash
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:

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

```

Configure the client-side profile:

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

```

## 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`](https://github.com/apache/maka/blob/main/runtime-host-service.ts) for lifecycle logic and [`webrtc-stun-policy.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.