What Is the Apache Maka Runtime Host? Process Architecture and State Management

The Apache Maka Runtime Host is the long-lived central process that owns a single State Root, maintains an exclusive writer lease on all persisted data, and executes runtime work for multiple clients via IPC or WebSocket connections.

The Apache Maka Runtime Host serves as the durable execution engine for the Maka framework, providing a single source of truth for state management across desktop, TUI, CLI, and bot clients. According to the apache/maka source code, this process guarantees safe concurrent access by enforcing a sole-writer policy on the State Root directory, eliminating conflicted state or connection-dependent execution. It orchestrates all business logic through a fixed composition of domain modules while projecting read-only session views back to connected clients.

Core Responsibilities of the Apache Maka Runtime Host

The Runtime Host functions as the central authority for state persistence and execution coordination. It combines process-level identity management with exclusive resource ownership to ensure data integrity across client sessions.

State Root Ownership and Exclusive Writer Lease

The Host holds the exclusive writer lease on the State Root, the durable directory containing all persisted data. This single-writer design prevents conflicts by ensuring that only one process ever modifies the canonical state at a time. If the Host restarts, it recovers directly from this durable store, making the State Root the immutable source of truth rather than any transient client connection.

Process Identity and Module Composition

Every Runtime Host maintains a stable Host Epoch—a process-level identity that persists for the lifetime of the instance. At startup, the Host builds a fixed Host Composition in packages/runtime-host/src/server/host-composition.ts, wiring together domain modules that implement specific protocol operations such as scheduled tasks and access-credential handling. This composition remains immutable during the Host's lifetime, ensuring consistent business logic execution.

Multi-Client Orchestration

The Host serves multiple concurrent clients—including Desktop UI, TUI, CLI applications, and automated bots—via local IPC or authenticated WebSocket connections. While clients submit work through sessions and turns, they never own secondary Runtime instances. The Host mediates all execution through the Hosted Execution Authority (packages/runtime-host/src/server/hosted-execution-authority.ts), which admits and tracks root executions while preventing clients from directly modifying state.

Apache Maka Runtime Host Architecture

The Runtime Host implementation spans several key source files that define its core subsystems and coordination mechanisms.

Host Kernel

Located in packages/runtime-host/src/server/host-kernel.ts, the Host Kernel manages the fundamental process lifecycle. It acquires the State Root lease, starts transport listeners, authenticates incoming connections, and coordinates graceful shutdown sequences. The Kernel acts as the central dispatcher, routing authenticated requests to either the Kernel itself or the appropriate Domain Module based on operation type.

Domain Modules and Execution Control

Domain Modules group related protocol operations and define recovery, shutdown, and resource-release behaviors for specific business features. Each module registers with the Host Composition during startup. The Run Composer freezes the model-visible prompt, tool catalog, and provider options before any provider call, ensuring deterministic execution contexts.

Session Continuity and Client Capabilities

The Session Continuity Coordinator (packages/runtime-host/src/server/session-continuity-coordinator.ts) projects read-only, size-limited snapshots of the canonical Session state back to every connected Client. This allows multiple observers to track execution progress without write access. For bounded reverse interactions—such as triggering OS-specific actions on a local machine—the Client Capability Coordinator (packages/runtime-host/src/server/client-capability-coordinator.ts) manages reverse calls into Clients without transferring Session ownership.

Runtime Host Lifecycle Stages

The Runtime Host follows a strict five-stage lifecycle defined in the architecture documentation and implemented across the core server files.

1. Startup – Acquires the State Root lease, binds the composition identity, recovers domain modules from persisted state, starts internal schedulers, and publishes a Ready signal to accept connections.
2. Request – Authenticates connecting clients, enforces size and permission limits, and routes validated requests to the Host Kernel or the owning Domain Module.
3. Execution – Admits a root execution (Run) for the Session turn, coordinates model and tool work, persists durable facts to the State Root, and publishes live updates via the continuity coordinator.
4. Drain – Stops accepting new work while allowing in-flight executions to complete or become safely recoverable in the State Root.
5. Close – Shuts down listeners, drains pending operations, closes domain modules in reverse initialization order, releases the State Root lease, and exits the process.

Working with the Runtime Host CLI

The runtime-host-cli.ts file (packages/cli/src/runtime-host-cli.ts) implements the command interface for managing Host instances.

Starting and Serving a Host

Create an ephemeral Host with a new State Root lease:

# Set up a new host with desktop-client preset

maka runtime-host setup --principal user123 \
    --preset desktop-client --lifecycle on-demand \
    --defer-pairing-commit

# Serve on default local IPC endpoint

maka runtime-host serve --framed

Connecting Clients

Activate or reconnect to an existing Host by its root identifier:

maka runtime-host activate --framed --root-id <64-hex-root-id>

Project and Profile Management

Manage workspace targets and remote connection profiles:

# List all projects known to the host

maka runtime-host project list

# Add a project directory (resolves to canonical host path)

maka runtime-host project add /path/to/project --prefer

# Create a TLS profile for remote access

maka runtime-host profile set \
    --id remote1 --name "Remote TLS" \
    --transport tls --url wss://remote.example.com:7443/runtime-host \
    --expected-root-id <root-id>

Host Profiles describe connection targets—local IPC, TLS, plaintext, SSH, or libp2p—and remain Client-owned without mutating Host state.

Summary

• The Apache Maka Runtime Host is the sole writer to the State Root, providing durable, conflict-free state management across process restarts.
• It maintains a fixed Host Composition of domain modules and a stable Host Epoch identity throughout its lifecycle.
• Multiple clients connect via IPC or WebSocket, but the Hosted Execution Authority ensures only the Host admits and executes runtime work.
• Key implementation files include host-kernel.ts for process management, host-composition.ts for module wiring, and runtime-host-cli.ts for command-line interaction.
• The five-stage lifecycle—Startup, Request, Execution, Drain, and Close—ensures graceful resource management and data persistence.

Frequently Asked Questions

What is the relationship between the Runtime Host and the State Root?

The Runtime Host maintains an exclusive writer lease on the State Root directory for the entire duration of its process lifetime. According to the apache/maka source code, this single-writer guarantee ensures that all durable data resides in one canonical location, making the State Root the source of truth for recovery after restarts. No client or secondary process can write to the State Root while the Host owns the lease.

How does the Runtime Host handle multiple concurrent clients?

The Host accepts connections from multiple clients—including Desktop UI, TUI, CLI, and bots—via Session Continuity projections managed in session-continuity-coordinator.ts. While clients submit work and receive live updates, they access read-only, size-limited views of the Session state. The Host serializes all write operations through its Hosted Execution Authority, ensuring that only one execution context modifies the State Root at any time regardless of client count.

What happens during the Drain stage of the Runtime Host lifecycle?

During the Drain stage, the Host stops accepting new client connections and work submissions while allowing in-flight executions to complete or reach a recoverable checkpoint. The Host signals Domain Modules to release resources gracefully and persists pending state changes to the State Root. This stage ensures that no work is lost during shutdown before the Close stage releases the exclusive lease and terminates the process.

Where is the Runtime Host implementation located in the Apache Maka source code?

The core Runtime Host implementation resides in packages/runtime-host/src/server/, with host-kernel.ts managing the process lifecycle, host-composition.ts building the module registry, and hosted-execution-authority.ts controlling execution admission. Command-line interactions are implemented in packages/cli/src/runtime-host-cli.ts, while architectural documentation is available in docs/architecture/runtime-host-architecture.md.

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