How to Configure Network Settings in Apache Maka: Proxies and Timeouts Explained

Configure proxy servers and request timeouts in Apache Maka by editing settings.json or using the SettingsStore API in packages/storage/src/settings-store.ts.

Apache Maka centralizes all user-editable configuration in a JSON file called settings.json, located within your workspace's userData directory (for example, <Electron-userData>/workspaces/default/settings.json). This guide explains how to configure network proxies and request timeouts through multiple interfaces—UI, direct file editing, and programmatic API—based on the actual source code implementation in the apache/maka repository.

Where Maka Stores Network Settings

The settings.json file follows a schema defined in @maka/core/settings. The network section contains two primary configuration objects:

Sub-section	Purpose	Key Fields
network.proxy	Routes all outgoing HTTP requests through a proxy	host, port, username, password
network.timeoutMs	Sets the global request timeout threshold	Single integer in milliseconds

By default, timeoutMs is set to 30,000 ms (30 seconds) unless explicitly overridden.

The SettingsStore implementation in packages/storage/src/settings-store.ts handles all persistence operations. This includes a hasLegacyProxyCredentialFields helper that automatically migrates old credential formats to the current structure when files are first read. All writes use writeAtomicFile to prevent corruption from incomplete operations.

Configuring Network Settings via the UI

Maka exposes network configuration through Settings → Network across all three interfaces:

• Desktop application — Graphical panel for host, port, and timeout input
• TUI (Terminal UI) — Interactive terminal interface
• CLI — Command-line commands

When you modify values through any UI, the application writes updates back to settings.json through the same SettingsStore layer, ensuring consistent behavior regardless of interface.

Configuring Network Settings Programmatically

For automated scripts or headless environments, use the createSettingsStore factory function from @maka/storage.

Reading Current Network Configuration

import { createSettingsStore } from '@maka/storage';

const workspaceRoot = '/path/to/workspace';
const settingsStore = createSettingsStore(workspaceRoot);

const current = await settingsStore.get();
console.log('Current proxy:', current.network?.proxy);
console.log('Current timeout (ms):', current.network?.timeoutMs);

Setting an HTTP or SOCKS Proxy

await settingsStore.update({
  network: {
    proxy: {
      host: 'proxy.mycorp.com',
      port: 3128,
      username: 'myuser',
      password: 's3cr3t',
    },
  },
});

Important: The password value is not stored directly in settings.json. The SettingsStore automatically moves it to the encrypted credential-vault.json file and references it securely.

Changing the Global Request Timeout

await settingsStore.update({
  network: {
    timeoutMs: 120_000, // 2 minutes in milliseconds
  },
});

Security Considerations for Proxy Credentials

Maka separates sensitive credential storage from general configuration:

• settings.json — Stores proxy host, port, and username in plain JSON
• credential-vault.json — Stores encrypted passwords, referenced by the settings store

This separation allows version control of non-sensitive configuration while protecting credentials. The encryption mechanism is handled transparently by the SettingsStore—you pass the password to settingsStore.update() and the implementation manages vault storage.

Key Source Files Reference

File	Role
packages/storage/src/settings-store.ts	Core implementation of SettingsStore with read/write logic and legacy field migration
@maka/core/settings (TypeScript definitions)	AppSettings type declaration including the network branch structure
apps/desktop/src/renderer/components/NetworkSettings.tsx	Desktop UI component rendering the proxy and timeout configuration panel
credential-vault.json	Runtime-encrypted password storage (created dynamically, not in source)

Summary

• Configuration location — settings.json in your workspace's userData directory
• Two network settings — network.proxy for HTTP/SOCKS proxies, network.timeoutMs for global timeouts
• Default timeout — 30,000 ms unless changed
• Credential security — Passwords migrate automatically to encrypted credential-vault.json
• Three access methods — Desktop/TUI/CLI graphical interfaces, direct file editing, or SettingsStore API
• Atomic writes — All changes use writeAtomicFile to prevent corruption

Frequently Asked Questions

What is the default request timeout in Maka?

The default timeoutMs value is 30,000 milliseconds (30 seconds). You can increase this for slow networks or decrease it for faster failure detection in time-sensitive operations.

Where does Maka store proxy passwords?

Proxy passwords are not stored in settings.json. When you provide a password through settingsStore.update(), the implementation automatically extracts it to the encrypted credential-vault.json file and replaces the value with a reference. This keeps credentials secure while maintaining readable configuration files.

Can I configure network settings without the graphical interface?

Yes. You have two options: edit settings.json directly (ensure valid JSON and restart Maka), or use the programmatic API through createSettingsStore() from @maka/storage. The API approach is recommended for automation—it handles validation, encryption, and atomic file writing automatically.

Does Maka support SOCKS proxies or only HTTP proxies?

The source schema in @maka/core/settings defines a generic host/port structure for network.proxy. The actual protocol support depends on the underlying HTTP client configuration. Check your specific Maka version's documentation or source for SOCKS-specific implementation details.

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