# Apache Maka Runtime Policy Configuration and Mutation System Explained

> Learn about Apache Maka's runtime policy system. Explore its centralized JSON document for agent permissions, resource budgets, and feature toggles, updated via CAS workflow.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-31

---

**Apache Maka maintains a centralized JSON runtime-policy document that governs all agent permissions, resource budgets, and feature toggles, allowing atomic updates only through an optimistic concurrency (CAS) workflow exposed via `runtime.policy.*` RPC endpoints.**

The runtime policy configuration and mutation system in Apache Maka serves as the central nervous system for agent governance. This JSON-driven architecture, defined in [`packages/core/src/runtime-policy.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts), determines everything from LLM connection access to shell execution privileges, ensuring strict control over agent capabilities while supporting dynamic, thread-safe updates.

## Runtime Policy Document Structure

The policy document, persisted as [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json), contains eight primary sections that define operational boundaries. The `RuntimePolicy` TypeScript interface in [`packages/core/src/runtime-policy.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts) and the codec in [`packages/storage/src/runtime-policy/codec.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/codec.ts) enforce type safety and validation across these domains:

- **connectionCatalog**: Declares permitted LLM connections with fields like `id`, `name`, `model`, `enabled`, and optional `budget` constraints.
- **credentialVault**: Secures API keys and OAuth tokens mapped to specific connection IDs.
- **shell**: Controls subprocess execution through `enabled` flags and command `allowlist` arrays.
- **memory**: Toggles long-term memory and incognito (private) mode via boolean flags.
- **webSearch**: Enables or disables the built-in web-search tool.
- **personalization**: Stores UI preferences such as `assistantTone`.
- **budget**: Enforces global limits on `totalTokens` and `perTurn` consumption.
- **policyMetadata**: Immutable tracking fields including `revision`, `policyKind` ('map' | 'supervisor'), and `policyFingerprint`.

## The Optimistic Concurrency Mutation Workflow

Maka enforces policy changes exclusively through a compare-and-swap (CAS) mechanism to prevent race conditions. The mutation system involves four coordinated stages managed by the `HostRuntimePolicyCoordinator` class in [`packages/runtime-host/src/server/runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts).

### Query Phase

Clients initiate changes by calling `runtime.policy.query`, which returns the current policy snapshot including the critical `revision` field acting as a CAS token.

### Mutate Phase

The `runtime.policy.mutate` endpoint accepts an `expectedRevision` and an array of policy operations. The system supports `set`, `delete`, `add`, and `remove` operations defined in [`packages/storage/src/runtime-policy/operations.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts). If the stored revision differs from `expectedRevision`, the system returns a `policy_conflict` error, forcing the client to re-query.

### Coordinator Persistence

The coordinator performs atomic updates through `RuntimePolicyStores` ([`packages/storage/src/runtime-policy-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy-stores.ts)). It verifies the CAS token, applies operations graph-ically using the codec, and persists to [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json). If persistence fails, it returns `persistence_failed` and poisons the activation gate.

### Activation Gate Enforcement

The `RuntimePolicyActivationGate` class ([`packages/runtime-host/src/server/runtime-policy-activation-gate.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-activation-gate.ts)) blocks policy-dependent reads during updates or when the policy state is poisoned, ensuring no agent operation executes against an inconsistent or failed policy state.

## Implementing Policy Changes in Code

Developers interact with the policy system through RPC endpoints. Below are practical TypeScript implementations demonstrating common mutations.

### Querying Current Policy Status

```typescript
const current = await desktop.request('runtime.policy.query', {});
console.log('Revision:', current.revision);
console.log('Web search enabled?', current.policy.webSearch.enabled);

```

### Enabling Features and Setting Budgets

```typescript
const snap = await desktop.request('runtime.policy.query', {});

const ops = [
  { op: 'set', path: '/webSearch/enabled', value: true },
  { op: 'set', path: '/budget/totalTokens', value: 500_000 },
];

const mutated = await desktop.request('runtime.policy.mutate', {
  expectedRevision: snap.revision,
  operations: ops,
});
console.log('New revision:', mutated.revision);

```

### Activating Incognito Mode

```typescript
const { revision } = await desktop.request('runtime.policy.query', {});
await desktop.request('runtime.policy.mutate', {
  expectedRevision: revision,
  operations: [{ op: 'set', path: '/memory/incognito', value: true }],
});

```

### Adding New LLM Connections

```typescript
await desktop.request('runtime.policy.mutate', {
  expectedRevision: revision,
  operations: [
    {
      op: 'add',
      path: '/connectionCatalog/connections/-',
      value: {
        id: 'gpt-4',
        name: 'OpenAI GPT-4',
        model: 'gpt-4',
        enabled: true,
        budget: { perTurn: 2000 },
      },
    },
  ],
});

```

## Core Source Files and Architecture

The runtime policy system spans multiple packages with clear separation of concerns:

- **[[`packages/core/src/runtime-policy.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts)](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts)**: Defines the `RuntimePolicy` interface and type guards.
- **[[`packages/storage/src/runtime-policy/codec.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/codec.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/codec.ts)**: Handles JSON schema validation and encode/decode logic.
- **[[`packages/storage/src/runtime-policy/document-io.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/document-io.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/document-io.ts)**: Manages atomic file I/O and temporary file handling for [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json).
- **[[`packages/storage/src/runtime-policy-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy-stores.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy-stores.ts)**: Provides the `RuntimePolicyStores` class offering `getSnapshot`, `set`, and operation methods.
- **[[`packages/storage/src/runtime-policy/operations.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts)**: Defines `PolicyOperation` types including `set`, `add`, `remove`, and `delete`.
- **[[`packages/runtime-host/src/server/runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts)**: Implements the CAS verification and atomic mutation logic.
- **[[`packages/runtime-host/src/server/runtime-policy-activation-gate.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-activation-gate.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-activation-gate.ts)**: Enforces policy-dependent access control and poisoned state management.
- **[[`packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts)**: Contains end-to-end tests for conflict handling and persistence failures.

## Summary

- Apache Maka uses a single JSON document ([`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json)) to govern all agent permissions, budgets, and feature toggles.
- The policy schema in [`packages/core/src/runtime-policy.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts) defines eight primary sections including connection catalogs, credential vaults, and execution constraints.
- All mutations occur through an optimistic concurrency (CAS) workflow requiring an `expectedRevision` token to prevent race conditions.
- The `HostRuntimePolicyCoordinator` applies operations atomically, while `RuntimePolicyActivationGate` blocks unsafe access during updates or failures.
- Clients interact via `runtime.policy.query` and `runtime.policy.mutate` RPC endpoints using JSON Patch-style operations.

## Frequently Asked Questions

### What happens when two clients try to mutate the policy simultaneously?

When concurrent mutations occur, the first successful update increments the revision token. Subsequent requests bearing the stale `expectedRevision` receive a `policy_conflict` error and must re-query the current state before retrying. This ensures linearizable updates without locking.

### Can I manually edit the runtime-policy.json file while the agent is running?

Manual editing is strongly discouraged. The runtime maintains in-memory state through `RuntimePolicyStores` and uses temporary file swapping during writes. Manual changes bypass the CAS mechanism and may trigger the `persistence_failed` state, causing the `RuntimePolicyActivationGate` to poison execution until consistency is restored.

### How does the activation gate protect against policy violations?

The `RuntimePolicyActivationGate` intercepts policy-dependent operations—such as tool executions requiring credentials or shell commands—and validates them against the current policy snapshot. If the policy is being updated or has entered a poisoned state due to persistence errors, the gate blocks execution to prevent unauthorized or unsafe actions.

### What operation types are supported for policy mutations?

The system supports `set`, `delete`, `add`, and `remove` operations defined in [`packages/storage/src/runtime-policy/operations.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts). These JSON Patch-style operations allow granular modifications to specific paths like `/webSearch/enabled` or `/connectionCatalog/connections/-` without replacing the entire document.