How to Enable Safe Resume for Maka Sessions: A Complete Configuration Guide

To enable safe resume for Maka sessions, set the environment variable MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 before starting any Maka runtime (desktop, CLI, or headless host).

In the apache/maka repository, the safe resume feature protects users from unintentionally triggering model calls when resuming previously interrupted turns. By default, this capability is disabled, which means the runtime hides resume affordances or displays error messages when users attempt to continue paused sessions. Enabling safe-boundary resume is essential for production deployments where users need secure, transparent session continuation without unexpected token consumption.

What Is Safe-Boundary Resume in Maka?

Safe-boundary resume is a security feature that guards against accidental model invocations during session recovery. When enabled, the Maka runtime validates that a continuation is explicitly requested before replaying stored transcripts or instantiating new sandboxes.

According to the architecture documentation in docs/architecture/runtime-resume-phase1-safe-boundary-contract.md (lines 28-29), this feature implements a strict UI/CLI contract that separates the resume request from the actual model execution. This prevents the auto-resume path from consuming tokens until a safe continuation is confirmed.

How to Enable Safe Resume for Maka Sessions

Enabling safe resume requires configuring one environment variable across all entry points.

Step 1: Export the Environment Variable

Set MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 in your shell, container environment, or .env file:

# For current shell session

export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

# .env file

MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

Step 2: Start the Maka Runtime

Launch your preferred Maka interface with the variable present in the environment:

# Desktop client

maka

# Or CLI mode

maka --cli

# Or runtime host directly

npm run start:runtime-host

Step 3: Verify the Configuration

Confirm that the feature is active by checking for resume affordances:

• Desktop UI: Look for the "Safe resume" action button on the interrupted-turn banner (defined in packages/ui/src/runtime-resume-copy.ts)
• CLI: Execute /resume—it should proceed without error instead of refusing immediately
• Headless/Auto-resume: The path should re-instantiate sandboxes and replay transcripts only after explicit confirmation

Technical Implementation Details

The runtime evaluates the safe resume flag during initialization and gates all resume pathways based on this configuration.

In packages/runtime-host/src/server/execution-composition.ts (line 1056), the runtime checks:

const safeBoundaryResumeEnabled =
  process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME === '1';

When this evaluates to false, the CLI runner in packages/cli/src/pi-tui-runner.ts (line 356) presents users with a clear error message:

{
  text: 'Safe‑boundary resume is not enabled on this runtime (set MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 to enable).',
}

The README.md (line 200) documents that this variable defaults to undefined, effectively disabling the feature until explicitly activated.

Platform-Specific Configuration Examples

Linux/macOS (Bash/Zsh)

Add to your shell profile for persistence:

echo 'export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell)

$env:MAKA_RUNTIME_SAFE_BOUNDARY_RESUME="1"
maka

Docker/Container Environments

ENV MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

Or via docker-compose:

environment:
  - MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

Summary

• Safe resume is disabled by default in apache/maka to prevent unintended model calls during session recovery.
• Set MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 in your environment before launching any Maka runtime (desktop, CLI, or headless host).
• Verification: The desktop UI displays a "Safe resume" button, while the CLI command /resume functions without error messages.
• Source locations: Configuration is read in packages/runtime-host/src/server/execution-composition.ts (line 1056) and error handling resides in packages/cli/src/pi-tui-runner.ts (line 356).

Frequently Asked Questions

What is the default behavior for Maka session resume?

By default, Maka disables safe-boundary resume. When users attempt to resume interrupted turns, the CLI displays an error message stating that safe-boundary resume is not enabled, and the desktop UI hides the resume affordance to prevent accidental token consumption.

Do I need to restart Maka after changing the environment variable?

Yes. Maka reads process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME during process initialization in packages/runtime-host/src/server/execution-composition.ts. Changes to environment variables require a full restart of the desktop client, CLI process, or runtime host to take effect.

Which Maka runtimes support safe-boundary resume?

All three primary entry points support the feature when the variable is set: the desktop application (which exposes the "Safe resume" banner), the CLI runner (which enables the /resume command), and the headless runtime host (which manages the auto-resume path and sandbox re-instantiation).

Where does Maka check for the safe resume configuration?

The primary check occurs in packages/runtime-host/src/server/execution-composition.ts at line 1056, where the code evaluates process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME === '1'. The CLI runner in packages/cli/src/pi-tui-runner.ts (line 356) contains the user-facing error logic, while packages/ui/src/runtime-resume-copy.ts manages the UI copy for resume actions.

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