# Environment Variables to Enable Crash Recovery in Apache Maka

> Discover Maka environment variables like MAKA_RUNTIME_SAFE_BOUNDARY_RESUME and MAKA_RUNTIME_RESUME_* for robust crash recovery and deterministic testing. Optimize your Apache Maka applications.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Set `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` to enable the safe-resume feature for production workloads, and use the `MAKA_RUNTIME_RESUME_*` variable family to orchestrate deterministic crash-recovery tests.**

Apache Maka’s deterministic execution engine relies on specific environment variables to activate crash recovery mechanisms in both production deployments and automated test harnesses. Understanding these variables is essential for operators enabling fault tolerance and developers verifying resume behavior across unexpected termination scenarios. The runtime host evaluates these flags during execution composition to decide whether to surface resume options in the Desktop UI and CLI.

## Core Environment Variables for Crash Recovery

Maka distinguishes between **production safe-resume** functionality and **test harness crash simulation** through two distinct categories of environment variables.

### Production Safe-Resume Flag

The primary environment variable to enable crash recovery in Apache Maka is **`MAKA_RUNTIME_SAFE_BOUNDARY_RESUME`**. When set to `1`, this flag activates the safe-resume capability that powers the Desktop "Safe resume" button, the CLI `/resume` command, and automatic startup resume.

Without this flag, the runtime host disables crash recovery entirely. According to the source code in [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts) at line 928, the runtime host checks this variable when creating the execution composition to determine whether to expose resume functionality. The architecture guide at [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md) (line 846) documents this behavior as the gatekeeper for all user-visible resume features.

```bash

# Enable safe-resume for desktop or CLI sessions

export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

```

### Test Harness Crash Simulation Variables

For testing crash recovery deterministically, Maka uses a family of `MAKA_RUNTIME_RESUME_*` variables defined in [`packages/runtime/src/__tests__/runtime-resume-crash.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/runtime-resume-crash.test.ts). These variables allow the test harness to spawn child processes that simulate crashes after writing committed event prefixes.

The complete set includes:

- **`MAKA_RUNTIME_RESUME_CRASH_CHILD=1`** — Signals the child process to simulate a crash after writing a committed prefix (lines 40–41).
- **`MAKA_RUNTIME_RESUME_WORKSPACE`** — Specifies the temporary workspace path where the child writes runtime events (lines 57–58).
- **`MAKA_RUNTIME_RESUME_SESSION`** — Provides the session identifier whose events require recovery (lines 24–25).
- **`MAKA_RUNTIME_RESUME_RUN`** — Identifies the specific run (invocation) being recovered (lines 25–26).
- **`MAKA_RUNTIME_RESUME_FINALLY_MARKER`** — Defines a file path the child writes in its `finally` block; the parent verifies this file does **not** exist after killing the child, confirming the crash occurred before finalization (lines 26–27).
- **`MAKA_RUNTIME_RESUME_EVENTS`** — Base-64-encoded JSON array of `RuntimeEvent` objects the child appends before crashing (lines 60–63).

## Practical Implementation

To enable crash recovery in production, set the safe-boundary flag before launching the runtime host:

```typescript
// Enable safe-resume for a desktop or CLI session
process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME = '1';

```

In test environments, the harness spawns a child process with the crash-simulation variables:

```typescript
// In a test harness – spawn a child that will crash after committing events
const child = spawn(process.execPath, [testFileUrl], {
  env: {
    ...process.env,
    MAKA_RUNTIME_RESUME_CRASH_CHILD: '1',
    MAKA_RUNTIME_RESUME_WORKSPACE: workspaceRoot,
    MAKA_RUNTIME_RESUME_SESSION: sessionId,
    MAKA_RUNTIME_RESUME_RUN: runId,
    MAKA_RUNTIME_RESUME_FINALLY_MARKER: markerPath,
    MAKA_RUNTIME_RESUME_EVENTS: Buffer.from(JSON.stringify(events), 'utf8')
      .toString('base64'),
  },
});

```

Inside the child process, the runtime checks for `MAKA_RUNTIME_RESUME_CRASH_CHILD` to enter the crash simulation branch. The child writes events to the durable `runtime.sqlite` store using the provided workspace, session, and run identifiers, then awaits termination:

```typescript
// Inside the crashing child (runtime-resume-crash.test.ts)
if (process.env.MAKA_RUNTIME_RESUME_CRASH_CHILD === '1') {
  const workspace = requiredEnv('MAKA_RUNTIME_RESUME_WORKSPACE');
  const session = requiredEnv('MAKA_RUNTIME_RESUME_SESSION');
  const run = requiredEnv('MAKA_RUNTIME_RESUME_RUN');
  const events = JSON.parse(
    Buffer.from(requiredEnv('MAKA_RUNTIME_RESUME_EVENTS'), 'base64').toString('utf8')
  );
  const store = createWorkspaceRuntimeStore(workspace);
  for (const ev of events) {
    await store.appendRuntimeEvent(session, run, ev);
  }
  // Signal readiness, then wait to be SIGKILL-ed
  process.stdout.write('READY\n');
  await new Promise(() => {}); // keep alive until parent kills us
}

```

After the parent kills the child, Maka reopens the durable store, verifies that only the committed prefix survived, and rebuilds a deterministic `ResumePlan` to continue execution.

## Summary

- **`MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1`** is the single environment variable required to enable crash recovery in production Apache Maka deployments, activating Desktop and CLI resume features.
- **Six test-specific variables** (`MAKA_RUNTIME_RESUME_CRASH_CHILD`, `MAKA_RUNTIME_RESUME_WORKSPACE`, `MAKA_RUNTIME_RESUME_SESSION`, `MAKA_RUNTIME_RESUME_RUN`, `MAKA_RUNTIME_RESUME_FINALLY_MARKER`, and `MAKA_RUNTIME_RESUME_EVENTS`) orchestrate deterministic crash simulation in the test harness defined in [`packages/runtime/src/__tests__/runtime-resume-crash.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/runtime-resume-crash.test.ts).
- The runtime host evaluates these flags during execution composition, as implemented in [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts), to decide whether to offer safe-resume options.
- These variables enable Maka to detect crash scenarios, provide full context to child processes, and verify that committed event prefixes survive unexpected termination.

## Frequently Asked Questions

### What is the minimum configuration to enable crash recovery in Apache Maka?

Set the environment variable `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` before starting the runtime host. This single flag enables the safe-resume feature in both the Desktop interface and CLI, allowing users to resume executions from the last committed boundary after an unexpected crash.

### How does Apache Maka test crash recovery deterministically?

The test harness uses `MAKA_RUNTIME_RESUME_CRASH_CHILD=1` to spawn child processes that intentionally crash after writing specific events. The harness passes workspace paths, session identifiers, and base64-encoded event arrays via `MAKA_RUNTIME_RESUME_WORKSPACE`, `MAKA_RUNTIME_RESUME_SESSION`, `MAKA_RUNTIME_RESUME_RUN`, and `MAKA_RUNTIME_RESUME_EVENTS`. After killing the child, the parent verifies that `MAKA_RUNTIME_RESUME_FINALLY_MARKER` was never written, confirming the crash occurred before finalization.

### Where does Apache Maka check for the safe-resume environment variable?

The runtime host checks for `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` in [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts) at line 928 when constructing the execution composition. This check determines whether to expose resume commands in the UI and CLI, as documented in the architecture guide at [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md).

### What happens if `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` is not set?

Without this environment variable, Apache Maka disables crash recovery entirely. The runtime host will not offer the "Safe resume" button in the Desktop application, the `/resume` command will be unavailable in the CLI, and automatic startup resume will not function, even if durable runtime stores contain recoverable event data.