What Surfaces Communicate with Maka's Runtime Host? A Complete Guide to Apache Maka Client Interfaces

Maka's Runtime Host accepts execution requests from four primary surfaces: the Desktop graphical UI, Terminal UI (TUI), command-line interface (CLI), and programmatic Eval API, each using distinct transport mechanisms ranging from WebSockets and SSH to local IPC pipes.

Apache Maka is an open-source execution platform where the Runtime Host serves as the core service responsible for running "subjects"—tasks, commands, and experiments. Understanding which surfaces communicate with Maka's Runtime Host is essential for architects integrating Maka into diverse environments, from interactive desktop applications to automated CI/CD pipelines. Each surface offers unique capabilities while relying on the same underlying protocol to dispatch work to the host.

The Four Primary Surfaces That Communicate with Maka's Runtime Host

Desktop Graphical UI

The Desktop UI provides the full interactive experience including chat interfaces, composer panels, tool orchestration, and workflow management. According to the Apache Maka source code, this surface connects to the Runtime Host over TLS, SSH, or plain WebSocket when explicitly enabled. The Desktop client can launch a local Runtime Host process via apps/desktop/src/main/runtime-host-boot.ts or attach to a remote instance, forwarding user actions such as message queue operations and scheduled-task triggers through the established connection.

Terminal UI (TUI)

The Terminal UI (TUI) offers a lightweight, scriptable interface for power users while rendering the interface directly in the terminal. It utilizes the same transport stack as the Desktop—TLS, SSH, or WebSocket—to issue Runtime Host protocol messages including turn.message.submit and queue.entry.promote. This surface bridges the gap between full graphical interaction and automation, providing interactive capabilities without the overhead of a native GUI.

Command-Line Interface (CLI)

The Command-Line Interface (CLI) operates as a non-interactive surface that invokes the Runtime Host directly through the runtime-host-tooling bundled with the CLI package. Rather than using network transports, the CLI sends JSON-encoded commands—such as Eval subjects and scheduled-task requests—over the Runtime Host's IPC mechanism, utilizing named pipes on Windows and Unix sockets on other platforms. This design enables automation scenarios and CI/CD pipelines through commands like maka eval … or maka schedule ….

Eval API (Programmatic Interface)

The Eval API treats the Runtime Host as a black-box execution service, creating "subjects" that describe commands, arguments, environment bindings, and result contracts. As documented in packages/eval/README.md, this surface asks the Runtime Host to execute these subject definitions programmatically, making it ideal for application integration where direct process management is required.

Transport Mechanisms and Security Models

Network Transports for Interactive Surfaces

Both the Desktop and TUI surfaces support multiple network transports when communicating with the Runtime Host. The implementation in docs/runtime-host-remote-access.md describes how these clients establish connections over TLS for encrypted communication, SSH for secure remote shell tunnels, or plaintext WebSocket when explicitly configured for local development.

Local IPC for CLI Automation

In contrast to the network-based interactive surfaces, the CLI relies on local inter-process communication (IPC) mechanisms. The Runtime Host creates platform-specific channels—named pipes on Windows and Unix domain sockets on Linux and macOS—to receive commands from the CLI tooling. This eliminates network overhead for local automation while maintaining the same protocol semantics as remote connections.

Remote Access Architecture

All three client surfaces—Desktop, TUI, and CLI—can operate against remote Runtime Host instances. The remote-access design documented in docs/runtime-host-remote-access.md (lines 20-27) explains that these surfaces may connect to a Runtime Host running on another machine using the same transport options. When operating remotely, the client forwards identical protocol messages; only the transport layer differs, maintaining consistency across local and distributed deployments.

Code Implementation Examples

The following examples demonstrate how different surfaces initialize connections and send commands to the Runtime Host.

Booting a Local Runtime Host from Desktop

When the Desktop application starts locally, it spawns the Runtime Host process and establishes communication channels:

// apps/desktop/src/main/runtime-host-boot.ts
import { spawn } from "child_process";

const host = spawn("node", ["-r", "ts-node/register", "runtime-host.ts"], {
  stdio: "inherit",
});
// The Desktop process now pipes user actions to `host.stdin`/`host.stdout`.

Executing Commands via CLI

The CLI surface sends Eval subjects directly to the local Runtime Host through IPC:

# Run a simple shell command through the Runtime Host

maka eval --command "ls -l /tmp" --contract protocol-v1

Establishing Remote Connections

For remote operation, surfaces can tunnel connections through SSH or connect directly via TLS:

# From a machine that can SSH to the host

ssh user@remote-host "npx maka-runtime-host setup --listen loopback"

# Then on the local client:

maka runtime-host --remote ssh://user@remote-host

Programmatic Subject Creation

The Eval API surface constructs subject objects programmatically before handing them to the Runtime Host:

import { createSubject } from "@maka/eval";

const subject = createSubject({
  command: "node",
  args: ["script.js"],
  env: { NODE_ENV: "production" },
  contract: "protocol-v1",
});

await runtimeHost.execute(subject);

Summary

• Four distinct surfaces communicate with Maka's Runtime Host: Desktop UI, TUI, CLI, and Eval API.
• Desktop and TUI use network transports (TLS, SSH, WebSocket) to support both local and remote Runtime Host connections.
• CLI utilizes local IPC mechanisms (named pipes or Unix sockets) for automation and scripting scenarios.
• Eval API provides a programmatic black-box interface for embedding Runtime Host capabilities within applications.
• All interactive surfaces share the same protocol semantics regardless of whether they connect locally or remotely, as documented in docs/runtime-host-remote-access.md.

Frequently Asked Questions

Can the Desktop UI connect to a remote Runtime Host?

Yes. The Desktop surface supports remote connections over TLS, SSH, or plain WebSocket when explicitly enabled. According to the remote-access documentation, the Desktop client can attach to a Runtime Host running on another machine while forwarding the same protocol messages used in local mode.

What transport does the Maka CLI use for local execution?

The CLI uses the Runtime Host's IPC mechanism rather than network sockets. On Windows, it communicates through named pipes; on Unix-like systems, it uses Unix domain sockets. This is implemented in the runtime-host-tooling bundled with the CLI package.

How does the Eval API differ from the CLI interface?

While the CLI provides a command-line interface for humans and scripts, the Eval API is a programmatic interface that treats the Runtime Host as a black-box service. The Eval API creates subject objects describing commands, arguments, and environment bindings, then requests execution directly, making it suitable for application integration rather than shell automation.

Are all Maka surfaces capable of running scheduled tasks?

Yes. All four surfaces—Desktop, TUI, CLI, and Eval API—can trigger scheduled-task operations. The Desktop and TUI forward scheduled-task triggers through their protocol connections, while the CLI provides explicit commands like maka schedule, and the Eval API can construct subjects that represent scheduled workloads.

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