Understanding the Runtime Host in Apache Maka: Architecture and Responsibilities

The Runtime Host is the long-lived, authoritative process that owns a single State Root and executes all Runtime work, ensuring single-writer consistency while clients act as thin requesters rather than state owners.

The Runtime Host serves as the central nervous system of the Apache Maka ecosystem. Unlike traditional architectures where each client maintains its own runtime, Maka consolidates all durable state and execution logic into this singular process. This design eliminates conflicting writes and provides clear authority for all state transitions across Desktop, TUI, CLI, and bot clients.

What is the Runtime Host in Maka?

The Runtime Host is the sole process that holds an exclusive lease on the State Root—the canonical source of durable state in the system. According to the Apache Maka source code, instead of distributing runtime logic across multiple clients, the Host centralizes execution while exposing a unified interface for client interaction.

This architecture provides several critical guarantees that distinguish Maka from multi-runtime systems.

Core Guarantees and Architectural Benefits

Single Writer of Durable State

Only the Runtime Host holds the exclusive lease on the State Root, preventing conflicting writes from multiple runtimes. This single-writer guarantee ensures that durable stores—the source of truth—are refreshed exclusively by the Host. In packages/runtime-host/src/server/host-kernel.ts, the Host Kernel manages this lease, allowing the system to recover after crashes without spawning a second Runtime.

Process-Level Authority

The Host Kernel controls the complete lifecycle of the process, including start, drain, and shutdown operations. Business logic is delegated to Domain Modules, but the Host maintains ultimate authority over process boundaries. This separation between kernel concerns and domain logic appears in the startup composition defined in packages/runtime-host/src/server/host-composition.ts.

Session Continuity and Client Isolation

The Runtime Host publishes size-limited live updates to Clients via the Session Continuity Coordinator (packages/runtime-host/src/server/session-continuity-coordinator.ts). When clients disconnect, they rebuild their view from canonical snapshots supplied by the Host—not from local state. This ensures consistent session continuity regardless of client network stability.

Controlled Client Capabilities

Clients can publish bounded capabilities (such as OS-facing actions) that the Host may invoke via reverse calls. However, ownership of the Session never leaves the Host. The Client Capability Coordinator (packages/runtime-host/src/server/client-capability-coordinator.ts) handles the publishing, binding, and bounded reverse-call lifecycle, ensuring that client-side effects remain strictly controlled.

Execution Management and Workspace Resolution

Workspace Resolution

The Host converts a WorkspaceTarget—whether a project ID or host path—into a canonical Host path. This resolution happens in packages/runtime-host/src/server/workspace-resolver.ts, ensuring that all clients reference the same physical workspace regardless of how they specify the target.

Execution Admission Control

The Hosted Execution Authority (packages/runtime-host/src/server/hosted-execution-authority.ts) guarantees that only one top-level execution runs per Session. This prevents race conditions and ensures deterministic execution flow, with static coordinators assembled in packages/runtime-host/src/server/execution-composition.ts.

Scheduled Task Durability

Scheduled tasks run inside the Host's Domain Modules rather than on clients, ensuring they survive client disconnects. This design guarantees that background work continues even when the initiating client closes its connection.

Client Interaction Patterns

Clients connect to the Runtime Host through a unified transport layer that treats local IPC and authenticated WebSocket connections identically. Both share the same routing table and permission model, simplifying security and debugging across local and remote scenarios.

Connecting a CLI or TUI client requires using the createRuntimeHostClient factory:

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

async function startSession(projectId: string) {
  const client = await createRuntimeHostClient({
    profile: 'remote',    // or 'local' for IPC
    stateRoot: undefined, // let the Host pick the current State Root
  });

  const session = await client.openSession({
    workspace: { kind: 'project', projectId },
  });

  await session.submitMessage({ role: 'user', content: 'Explain the weather.' });

  for await (const update of session.updates()) {
    console.log('Update:', update);
  }
}

The client submits messages (turns) to the Host, which owns the execution. For operations requiring client-side effects, the Host invokes published capabilities:

// Client publishes capability
await client.publishCapability({
  name: 'openFile',
  schema: { type: 'object', properties: { path: { type: 'string' } } },
});

// Host invokes during execution
await runtimeHost.invokeCapability('openFile', { path: '/tmp/report.pdf' });

Key Implementation Files

The Runtime Host implementation spans several critical files in the packages/runtime-host/src/server/ directory:

• host-kernel.ts: Manages process lifetime, the exclusive lease on the State Root, and graceful shutdown listeners.
• host-composition.ts: Defines the fixed startup composition of modules and stores, including recovery order.
• execution-composition.ts: Assembles static coordinators for execution flow management.
• hosted-execution-authority.ts: Controls admission, completion, and settlement of top-level Session executions.
• session-continuity-coordinator.ts: Provides canonical snapshots and live stream updates to Clients.
• client-capability-coordinator.ts: Handles publishing, binding, and lifecycle management for client capabilities.
• workspace-resolver.ts: Resolves WorkspaceTarget inputs to canonical Host directory paths.

These files collectively implement the Host's role as the single source of truth for workspace resolution, execution admission, and durable state management.

Summary

• The Runtime Host acts as the sole owner of the State Root, providing a single-writer guarantee for all durable state in Apache Maka.
• It centralizes execution authority while delegating business logic to Domain Modules, preventing race conditions through the Hosted Execution Authority.
• Clients function as thin requesters that consume session continuity updates and publish bounded capabilities, but never own session state.
• The architecture unifies local IPC and remote WebSocket transport under identical security and routing models.
• Key source files in packages/runtime-host/src/server/ implement process lifecycle, workspace resolution, and client capability coordination.

Frequently Asked Questions

What is the difference between the Runtime Host and a Client in Maka?

The Runtime Host is the long-lived process that owns the State Root and executes all Runtime work, while Clients (Desktop, TUI, CLI, or bots) are transient processes that request work from the Host. Clients do not maintain their own runtime or durable state; they rely on the Host for canonical snapshots and session continuity.

How does the Runtime Host prevent conflicting writes to state?

The Host maintains an exclusive lease on the State Root, making it the only process capable of writing to durable stores. This single-writer architecture, implemented in host-kernel.ts, ensures that all state transitions occur through one authoritative process, eliminating conflicts that would arise from multiple independent runtimes.

Can scheduled tasks survive if a Client disconnects?

Yes. Scheduled tasks execute inside the Host's Domain Modules rather than on the Client, ensuring they continue running even after the initiating Client disconnects. The Host's durable state management guarantees task persistence across client sessions.

How do Clients perform OS-level actions if the Host owns execution?

Clients publish bounded capabilities (such as file system access) through the Client Capability Coordinator. The Host can then invoke these capabilities via reverse calls during execution, but the Session ownership remains with the Host. This pattern allows controlled client-side effects without compromising the Host's authority over state.

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