# How to Configure Apache Maka: Complete Guide to Settings.json, CLI, and UI

> Learn to configure Apache Maka using settings.json, CLI, and UI. This comprehensive guide covers all essential settings for your Apache Maka instance.

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

---

**Apache Maka stores all user-editable configuration in a [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) file inside the Electron userData directory, which you can modify through the Desktop UI, CLI commands, or direct file edits.**

Apache Maka is an open-source desktop application that centralizes configuration management through a structured JSON schema. Whether you are customizing themes, configuring AI model connections, or adjusting workspace defaults, you configure Apache Maka through three complementary interfaces that all write to the same underlying `AppSettings` object defined in the core source code.

## Where Apache Maka Stores Configuration

All persistent settings live in a JSON file named [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) located within the Electron *userData* directory. The typical path is `~/.config/maka/workspaces/default/` on Linux, with equivalent locations on macOS and Windows.

At startup, the **Runtime Host** initializes the **SettingsStore** by calling `createSettingsStore(workspaceRoot)` in [`packages/storage/src/settings-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/settings-store.ts). The `FileSettingsStore` class reads the JSON file through its `get()` method, validates the structure using normalization helpers from [`packages/core/src/settings.ts`](https://github.com/apache/maka/blob/main/packages/core/src/settings.ts), and caches the resulting `AppSettings` object for use by both the UI and CLI.

## Three Ways to Configure Apache Maka

### Desktop UI Settings

The simplest method to configure Apache Maka is through the built-in Settings drawer. Click the gear icon to open [`apps/desktop/src/renderer/settings/settings-modal.tsx`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/settings/settings-modal.tsx), which renders form controls for each settings section defined in the core schema. Changes made in the UI are sent via IPC through [`apps/desktop/src/main/settings-ipc-helpers.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/main/settings-ipc-helpers.ts) to the main process, which calls `FileSettingsStore.update(patch)` to persist the changes.

### Command Line Interface

For automation and scripting, use the built-in `settings` command:

```bash

# Set the default AI model

maka settings set models defaultModel claude-3-opus

# Enable the web-search sub-agent

maka settings set subagents.enabled true

# Configure search API key

maka settings set search.apiKey YOUR_TAVILY_KEY

```

The CLI sends patches to the same `FileSettingsStore.update()` method used by the UI, ensuring consistency across interfaces.

### Direct JSON Editing

For bulk changes or version-controlled configurations, edit [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) directly:

```json
{
  "appearance": {
    "theme": "dark",
    "themePalette": "nord",
    "appIcon": "sky",
    "appIconDark": "ink"
  },
  "models": {
    "defaultModel": "gpt-4o",
    "connections": [
      {
        "id": "openai-gpt4o",
        "type": "openai",
        "apiKey": "YOUR_OPENAI_KEY",
        "model": "gpt-4o",
        "provider": "openai"
      }
    ]
  },
  "permissions": {
    "permissionMode": "managed"
  }
}

```

Save the file and restart Maka to load the new configuration. The `normalizeSettings` function in [`packages/core/src/settings.ts`](https://github.com/apache/maka/blob/main/packages/core/src/settings.ts) validates the structure on next launch.

## Key Configuration Sections

The `AppSettings` schema in [`packages/core/src/settings.ts`](https://github.com/apache/maka/blob/main/packages/core/src/settings.ts) organizes configuration into typed sections:

- **general**: Global defaults including `locale` and `autoUpdate` behavior.
- **appearance**: Theme control through `theme`, `themePalette`, `appIcon`, and `appIconDark` options.
- **projects**: Workspace configuration with `defaultWorkspace` and `workspaceRoot` paths.
- **memory**: Local cache settings including `enabled` flag and `maxEntries` limits.
- **models**: AI provider configuration using the `ModelConnection` type, including `defaultModel` and API keys in the `connections` array.
- **subagents**: Toggle built-in agents like web-search and code-review via the `enabled` boolean and `options` object.
- **external-agents**: User-supplied agent definitions stored in the `agents` array (type `ExternalAgentConfig`).
- **search**: Web-search provider setup with `apiKey` and `rateLimit` for services like Tavily.
- **permissions**: Security mode selection via `permissionMode` (`managed` or `bypass`) and associated `labels`.
- **usage**: Telemetry configuration with `enabled`, `range`, and `status` fields.
- **daily-review**: Automated scheduling using `cron` expressions and `reviewPrompt` settings.

## How the Configuration System Works

The configuration pipeline follows a strict validation flow:

1. **Initialization**: The Runtime Host invokes `createSettingsStore()` with the workspace root path.
2. **Validation**: `FileSettingsStore.get()` reads [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) and applies `normalizeSettings()` from [`packages/core/src/settings.ts`](https://github.com/apache/maka/blob/main/packages/core/src/settings.ts) to ensure type safety and default values.
3. **Distribution**: The validated `AppSettings` object travels via IPC ([`apps/desktop/src/main/settings-ipc-helpers.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/main/settings-ipc-helpers.ts)) to the Renderer process for UI consumption.
4. **Persistence**: Updates from any interface call `FileSettingsStore.update(patch)`, which merges changes, re-normalizes the data, and atomically writes back to disk.

## Summary

- Apache Maka configuration resides in [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) within the Electron userData directory (e.g., `~/.config/maka/workspaces/default/`).
- The **SettingsStore** class in [`packages/storage/src/settings-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/settings-store.ts) manages all read/write operations.
- You can configure Apache Maka via the Desktop Settings UI, the `maka settings` CLI, or direct JSON manipulation.
- The `AppSettings` schema in [`packages/core/src/settings.ts`](https://github.com/apache/maka/blob/main/packages/core/src/settings.ts) defines all valid sections including appearance, models, permissions, and subagents.
- All configuration methods ultimately invoke `FileSettingsStore.update()` to persist changes after validation.

## Frequently Asked Questions

### Where is the settings.json file located on my system?

The file is located in the Electron userData directory under [`workspaces/default/settings.json`](https://github.com/apache/maka/blob/main/workspaces/default/settings.json). On Linux this is typically `~/.config/maka/workspaces/default/settings.json`, while macOS uses `~/Library/Application Support/maka/` and Windows uses `%APPDATA%/maka/`.

### Can I configure Apache Maka without opening the desktop application?

Yes. You can use the CLI command `maka settings set <section> <key> <value>` to modify configuration from the terminal, or edit the [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) file directly with a text editor. Both methods work while the application is closed and take effect on next launch.

### What happens if I edit settings.json while Maka is running?

The application may overwrite your manual changes if it persists any UI state to disk. To avoid conflicts, close Maka before editing [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) directly, or use the CLI `maka settings` commands which safely acquire file locks and merge patches through the `FileSettingsStore.update()` API.

### How do I add a new AI model connection via configuration?

Add a new object to the `models.connections` array in [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) with the `ModelConnection` structure: include `id`, `type` (e.g., "openai"), `provider`, `model`, and `apiKey`. Alternatively, use the CLI: `maka settings set models.connections '[{"id":"custom","type":"openai","apiKey":"KEY","model":"gpt-4"}]'`.