What Is the Runtime Host in Apache Maka? Responsibilities and Architecture

The Runtime Host is the sole execution authority in the Apache Maka backend, responsible for session identity, agent lifecycle, tool execution, permissions management, and event logging.

Apache Maka is an open-source backend system for managing AI agent execution and tool runtime environments. The Runtime Host serves as the central coordinator that guarantees a single, consistent execution environment for all Maka workloads, acting as the bridge between clients and the underlying agent runtime.

Core Responsibilities of the Runtime Host

According to the architecture documentation in ARCHITECTURE.md, the Runtime Host owns the complete lifecycle of a running turn. The high-level flow diagram shows clients (Desktop, TUI, CLI, bots) sending work to Runtime Host → SessionManager → AgentRun + RuntimeKernel → Tool Runtime【https://github.com/apache/maka/blob/main/ARCHITECTURE.md#L24-L32】.

Session and Turn Identity Management

The Runtime Host creates and tracks unique session and turn identifiers for every execution. This ensures that every interaction within the Maka ecosystem has a distinct identity that can be traced and managed throughout its lifecycle, preventing collisions and enabling accurate audit trails.

Agent Lifecycle Control

All agent lifecycle operations flow through the Runtime Host. It controls the start-up, continuation, and termination of agents that run user code or tools. This centralized management prevents resource leaks and ensures agents operate within defined constraints established by the host's admission controls.

Centralized Tool Execution

Every tool invocation in Maka routes through the Runtime Host. Whether calling an LLM API or executing a shell command, the host acts as the gateway. The narrative text in the architecture overview states that the host owns "tools" alongside session identity and agent lifecycle【https://github.com/apache/maka/blob/main/ARCHITECTURE.md#L41-L42】.

Permission and Capability Enforcement

The Runtime Host enforces capability-based security. It manages which capabilities a client may use and handles admission of new capabilities. The registration logic in packages/runtime-host/src/control/registration.ts handles client registration and capability admission, ensuring only authorized clients access specific functions.

Runtime Event Logging

Every model message, tool call, result, and termination fact is written to the Runtime Event Log. This comprehensive logging creates an immutable record of execution, essential for debugging, auditing, and replaying agent sessions within the Maka ecosystem.

Architecture and Implementation

The Runtime Host implementation resides in the packages/runtime-host directory, documented as the "Sole hosted execution authority and public client/protocol"【https://github.com/apache/maka/blob/main/ARCHITECTURE.md#L72-L73】.

Key source files that implement these responsibilities include:

• ARCHITECTURE.md – High-level system map that defines the Runtime Host as the sole execution authority.
• packages/runtime-host/src/server/context-coordinator.ts – Coordinates read-only context queries as part of the host's public protocol.
• packages/runtime-host/src/control/registration.ts – Handles client registration and capability admission.
• packages/runtime-host/src/operator/setup-frame.ts – Sets up new Runtime Host instances, used by the maka runtime-host setup CLI command.
• packages/runtime-host/src/protocol/workspace.ts – Defines protocol messages for client-host interaction.

Working with the Runtime Host

You can interact with the Runtime Host through CLI commands or programmatically via the TypeScript client.

CLI Installation and Setup

Install and configure the Runtime Host service using the Maka CLI:

# Install the Runtime Host service (global persistent install)

maka runtime-host service install

# Set up a per-user Runtime Host instance

maka runtime-host setup --root "$HOME/.maka/runtime-host"

# Start the host (runs the event loop, listens for client connections)

maka runtime-host serve

These commands establish the execution authority on your local machine or server, creating the environment where agents and tools will run【https://github.com/apache/maka/blob/main/docs/runtime-host-remote-access.md#L31-L45】.

Programmatic Tool Execution

Connect to a running Runtime Host and execute tools through its public protocol:

import { RuntimeHostClient } from '@maka/runtime-host';

// Connect to the running host (WebSocket or Unix domain socket)
const client = new RuntimeHostClient({ url: 'ws://localhost:7443/runtime-host' });

// Execute a shell command via the host's tool runtime
await client.executeTool({
  tool: 'bash',
  args: ['-c', 'echo Hello from Maka'],
});

The RuntimeHostClient interacts with the protocol defined in packages/runtime-host/src/protocol/*, ensuring all tool execution goes through the host's authority rather than direct system calls.

Summary

• The Runtime Host is the single execution authority in Apache Maka, coordinating all backend operations.
• It manages session identity, agent lifecycle, tool execution, permissions, and event logging.
• Located in packages/runtime-host, it exposes a public protocol for CLI and programmatic access.
• All tool invocations route through the host, enabling centralized security and logging.
• Clients connect via WebSocket or Unix domain sockets to submit work through the RuntimeHostClient.

Frequently Asked Questions

What makes the Runtime Host the "sole execution authority" in Maka?

The Runtime Host is designated as the sole execution authority because all agent runs, tool invocations, and capability checks flow through it. As documented in ARCHITECTURE.md, it sits at the top of the execution flow, receiving client requests and delegating to the SessionManager and Tool Runtime, ensuring no code executes outside its oversight【https://github.com/apache/maka/blob/main/ARCHITECTURE.md#L24-L32】.

How does the Runtime Host handle tool execution?

All tool calls—including LLM invocations and shell commands—are routed through the Runtime Host's tool runtime. When using the RuntimeHostClient, the executeTool method sends requests to the host, which validates permissions, logs the event, and executes the tool in a controlled environment before returning results.

What is the relationship between the Runtime Host and the SessionManager?

The Runtime Host creates and owns session identities, then delegates session-specific operations to the SessionManager. According to the architecture flow, work moves from Runtime Host → SessionManager → AgentRun + RuntimeKernel, establishing a hierarchy where the host maintains ultimate authority while the SessionManager handles session-level coordination.

How do clients establish a connection to the Runtime Host?

Clients connect to the Runtime Host using the RuntimeHostClient class from @maka/runtime-host, specifying either a WebSocket URL (e.g., ws://localhost:7443/runtime-host) or a Unix domain socket path. The connection protocol is defined in packages/runtime-host/src/protocol/workspace.ts, which handles message serialization and capability negotiation during the initial handshake.

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