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

The Runtime Host in Maka is a long-lived process that owns a single State Root and executes all Runtime work, acting as the single source of truth for durable state while clients request work through IPC or WebSocket connections.

The Apache Maka project implements a centralized runtime architecture where the Runtime Host serves as the authoritative process for all stateful operations. Unlike traditional architectures where each client maintains its own runtime, Maka delegates all execution to this persistent Host, enabling durable, recoverable work across Desktop, TUI, CLI, and bot clients.

Core Responsibilities of the Runtime Host

The Runtime Host provides six essential architectural guarantees that eliminate conflicts between multiple independent runtimes.

Exclusive State Ownership

The Host holds the exclusive lease on the State Root, making it the single writer of durable state. This prevents conflicting writes from multiple runtimes and ensures that durable stores refresh only through the Host process. According to the source code in packages/runtime-host/src/server/host-kernel.ts, the Host Kernel manages this lease and controls the process lifecycle including start, drain, and shutdown operations.

Stable Durability Boundaries

By centralizing state transitions, the Host creates stable boundaries for durability. After a crash, the system recovers without spawning a second Runtime, as the canonical state persists within the Host's managed stores. The recovery order and fixed startup composition are defined in packages/runtime-host/src/server/host-composition.ts.

Session Continuity Management

The Host publishes size-limited live updates to Clients via the Session Continuity Coordinator implemented in packages/runtime-host/src/server/session-continuity-coordinator.ts. When Clients disconnect, they rebuild their view from canonical snapshots supplied by the Host, ensuring consistent session continuity across network interruptions.

Client Coordination and Execution Control

While the Host owns the state, Clients request work through a unified transport layer that supports both local IPC and authenticated WebSocket connections under the same routing table and permission model.

Workspace Resolution

The Host acts as the single source of truth for workspace resolution. In packages/runtime-host/src/server/workspace-resolver.ts, the system converts a WorkspaceTarget—whether a project ID or host path—into a canonical Host directory, ensuring all Clients reference the same filesystem tree.

Execution Admission and Scheduling

The HostedExecutionAuthority in packages/runtime-host/src/server/hosted-execution-authority.ts controls execution admission, guaranteeing that only one top-level execution runs per Session. This prevents race conditions and ensures that scheduled tasks survive client disconnects by running inside the Host's Domain Modules assembled by packages/runtime-host/src/server/execution-composition.ts.

Bounded Client Capabilities

Clients can publish bounded capabilities (such as OS-facing actions) that the Host may invoke via reverse calls. The ClientCapabilityCoordinator in packages/runtime-host/src/server/client-capability-coordinator.ts handles the publishing, binding, and lifecycle of these reverse calls, ensuring that ownership of the Session never leaves the Host even when executing client-side effects.

Connecting Clients to the Runtime Host

Clients connect to the Host using the @maka/runtime-host/client package. The following example demonstrates how a CLI or TUI client establishes a session:

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

// Resolve a workspace (project) and start a session
async function startSession(projectId: string) {
  const client = await createRuntimeHostClient({
    // Uses TLS/SSH/WebSocket depending on profile configuration
    profile: 'remote',               // or 'local' for IPC
    stateRoot: undefined,            // let the Host pick the current State Root
  });

  // Open a Session Continuity subscription
  const session = await client.openSession({
    workspace: { kind: 'project', projectId },
  });

  // Submit a message (a turn) to the Host
  await session.submitMessage({ role: 'user', content: 'Explain the weather.' });

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

This implementation illustrates the request-response flow: the Client asks the Host to perform work, the Host owns the execution, and updates stream back through the established connection.

Implementing Reverse Capability Calls

The Host can invoke client-published capabilities during execution. First, the client publishes a capability:

// Desktop publishes an OS-level capability
await client.publishCapability({
  name: 'openFile',
  schema: { type: 'object', properties: { path: { type: 'string' } } },
});

Then, during a Run, the Runtime Host calls it:

// Runtime Host can call it during a Run
await runtimeHost.invokeCapability('openFile', { path: '/tmp/report.pdf' });

This pattern maintains the Host's authority while allowing bounded client-side effects through explicit capability contracts defined in the schema.

Key Implementation Files

The following source files define the Runtime Host's architecture:

• packages/runtime-host/src/server/host-kernel.ts – Manages process lifetime, lease on the State Root, listeners, and graceful shutdown.
• packages/runtime-host/src/server/host-composition.ts – Defines the fixed startup composition (modules, stores) and recovery order.
• packages/runtime-host/src/server/execution-composition.ts – Assembles static coordinators for execution flow.
• packages/runtime-host/src/server/hosted-execution-authority.ts – Controls admission, completion, and settlement of top-level Session executions.
• packages/runtime-host/src/server/session-continuity-coordinator.ts – Provides canonical snapshots and live stream updates to Clients.
• packages/runtime-host/src/server/client-capability-coordinator.ts – Handles publishing, binding, and bounded reverse-call lifecycle for client capabilities.
• packages/runtime-host/src/server/workspace-resolver.ts – Resolves WorkspaceTarget (project ID or host path) to a canonical Host directory.
• docs/architecture/runtime-host-architecture.md – The authoritative design document describing the Host's architecture and responsibilities.

Summary

• The Runtime Host in Maka is a long-lived, authoritative process that owns a single State Root and serves as the single writer of durable state.
• It eliminates conflicts by centralizing execution, workspace resolution, and scheduled task management within Domain Modules.
• Clients connect via IPC or WebSocket to request work, while the Host maintains session continuity through canonical snapshots supplied upon reconnection.
• Execution admission controlled by HostedExecutionAuthority prevents race conditions by allowing only one top-level execution per Session.
• Bounded capabilities enable the Host to invoke client-side effects via reverse calls without transferring session ownership.
• All operations are coordinated through specific modules in packages/runtime-host/src/server/ as defined in the architecture documentation.

Frequently Asked Questions

How does the Runtime Host prevent conflicting state writes?

The Runtime Host maintains an exclusive lease on the State Root, making it the only process capable of writing to durable stores. According to the Apache Maka source code in packages/runtime-host/src/server/host-kernel.ts, this design ensures that regardless of how many Clients connect, only one runtime instance modifies the canonical state, preventing conflicting writes.

Can multiple Clients connect to the same Runtime Host simultaneously?

Yes. The Runtime Host supports multiple concurrent Clients including Desktop, TUI, CLI, and bots through a unified transport layer. As implemented in packages/runtime-host/src/server/session-continuity-coordinator.ts, the Host publishes size-limited live updates to all connected Clients while maintaining a single source of truth for the Session state.

What happens to running tasks when a Client disconnects?

Tasks continue executing within the Host's Domain Modules because the Host—not the Client—owns the execution. The HostedExecutionAuthority in packages/runtime-host/src/server/hosted-execution-authority.ts ensures that scheduled tasks and top-level executions survive client disconnects, with Clients rebuilding their view from snapshots upon reconnection.

How does the Runtime Host handle client-side operations like file system access?

The Host invokes bounded capabilities published by Clients through reverse calls. The ClientCapabilityCoordinator in packages/runtime-host/src/server/client-capability-coordinator.ts manages these permissions without transferring Session ownership, allowing the Host to request OS-facing actions while maintaining its role as the central authority.

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