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

> Learn how to configure network settings in Apache Maka. Master proxy servers and request timeouts by editing settings.json or using the SettingsStore API for efficient network management.

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

---

**Configure proxy servers and request timeouts in Apache Maka by editing [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) or using the `SettingsStore` API in [`packages/storage/src/settings-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/settings-store.ts).**

Apache Maka centralizes all user-editable configuration in a JSON file called **[`settings.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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

```typescript
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

```typescript
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`](https://github.com/apache/maka/blob/main/settings.json)**. The `SettingsStore` automatically moves it to the encrypted **[`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json)** file and references it securely.

### Changing the Global Request Timeout

```typescript
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`](https://github.com/apache/maka/blob/main/settings.json)** — Stores proxy host, port, and username in plain JSON
- **[`credential-vault.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/components/NetworkSettings.tsx) | Desktop UI component rendering the proxy and timeout configuration panel |
| [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) | Runtime-encrypted password storage (created dynamically, not in source) |

## Summary

- **Configuration location** — [`settings.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/settings.json)**. When you provide a password through `settingsStore.update()`, the implementation automatically extracts it to the encrypted **[`credential-vault.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.