# How to Configure Model Settings and Sandbox Settings in Maka's Desktop Workspace

> Learn how to configure model and sandbox settings in Maka Desktop Workspace using the Settings modal and the useSettingsModal hook. Easily open specific sections for your needs.

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

---

**You configure Model Settings and Sandbox Settings in Maka's Desktop workspace through the Settings modal, accessible via the `useSettingsModal` hook with `openSettingsSection('models')` or `openSettingsSection('sandbox')`.**

Maka's Desktop application provides a centralized **Settings** system for managing workspace behavior. Two critical configuration areas are **Model Settings**—which control LLM connections—and **Sandbox Settings**—which define security boundaries for tool execution. This article explains the architecture, source code implementation, and practical methods for configuring both.

## Opening the Settings Modal

The Desktop shell exposes the `useSettingsModal` hook to control settings navigation programmatically.

```tsx
// apps/desktop/src/renderer/app-shell.tsx
const { setSettingsOpen, openSettingsSection } = useSettingsModal();

```

This hook provides three key capabilities:

- `setSettingsOpen(true)` — displays the Settings modal
- `openSettingsSection('models')` — navigates directly to Model Settings
- `openSettingsSection('sandbox')` — navigates directly to Sandbox Settings

UI components throughout the application invoke these methods. For example, the chat message surface includes a "Go to Models" button that calls `openSettingsSection('models')` in [`apps/desktop/src/renderer/chat-message-surface.tsx`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/chat-message-surface.tsx). Similarly, workspace instruction panels trigger `openSettingsSection('sandbox')` for sandbox configuration.

## Configuring Model Settings

Model Settings manage connections to language model providers and the active model selection for each profile.

### Adding and Testing Model Connections

1. **Navigate to the Models tab** — Use the UI button or call `openSettingsSection('models')`

2. **Create a provider connection** — Select from supported providers (OpenAI, Azure, local models) and enter credentials

3. **Verify connectivity** — The UI executes a probe via `settings.update()` to validate the API key or local binary

4. **Set the default model** — Mark one connection as active for the current profile

The selected model persists in [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) at the workspace root. The storage layer in [`packages/storage/src/settings-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/settings-store.ts) handles read/write operations, applying defaults through `createDefaultSettings()` when the file is absent or incomplete.

### Model Settings Code Example

```ts
// Update model configuration programmatically
await window.maka.settings.update({
  models: {
    productionOpenAI: {
      kind: 'openai',
      apiKey: 'sk-xxxx…',        // encrypted at rest
      defaultModel: 'gpt-4o',
    },
    localLlama: {
      kind: 'local',
      binaryPath: '/opt/llama-server',
      port: 8080,
    },
  },
  activeModel: 'productionOpenAI',
});

```

## Configuring Sandbox Settings

Sandbox Settings define the security perimeter that protects the host system from potentially harmful tool outputs.

### Sandbox Capability Flags

The Sandbox tab exposes toggles for specific capabilities:

| Flag | Effect |
|------|--------|
| `allowScripts` | Permits JavaScript execution in HTML artifacts |
| `allowPopups` | Allows `window.open()` and popup creation |
| `allowDownloads` | Enables automatic file downloads |
| `allowSameOrigin` | Removes same-origin restrictions on iframes |

Each toggle corresponds to a standard HTML `sandbox` attribute value. Changes apply immediately to new tool executions; existing sessions require restart.

### Sandbox Enforcement Architecture

The sandbox boundary operates through three layers:

- **Runtime Host** — validates every tool request against stored policy via `@maka/core/sandbox-boundary`
- **Permission Prompts** — escalates violations through `sandbox_boundary_request` events, handled in [`app-shell-session-events.tsx`](https://github.com/apache/maka/blob/main/app-shell-session-events.tsx) and [`permission-response-guard.tsx`](https://github.com/apache/maka/blob/main/permission-response-guard.tsx)
- **Artifact Rendering** — executes HTML output in constrained iframes using [`artifact-preview.tsx`](https://github.com/apache/maka/blob/main/artifact-preview.tsx)

```tsx
// apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-preview.tsx
<iframe
  sandbox="allow-scripts allow-same-origin"
  src={artifactUrl}
/>

```

### Sandbox Settings Code Example

```ts
// Restrict sandbox to scripts only, block popups and downloads
await window.maka.settings.update({
  sandbox: {
    allowScripts: true,
    allowPopups: false,
    allowDownloads: false,
    allowSameOrigin: false,
  },
});

```

## Settings Persistence and Profiles

All configuration lives in **[`settings.json`](https://github.com/apache/maka/blob/main/settings.json)** at the workspace root. The storage system supports:

- **Per-profile isolation** — distinct Model and Sandbox configurations per Runtime Host profile
- **Atomic updates** — `settings.update()` patches merge safely without race conditions
- **Default fallback** — missing keys populate from `createDefaultSettings()`

```ts
// Read complete settings snapshot
const settings = await window.maka.settings.get();
console.log('Active model:', settings.activeModel);
console.log('Sandbox policy:', settings.sandbox);

```

## Summary

- **Access settings** through `useSettingsModal` hook with `openSettingsSection('models')` or `'sandbox'`
- **Model Settings** configure provider connections and default model selection per profile
- **Sandbox Settings** control security capabilities via capability flags that map to iframe sandbox attributes
- **Persistence** occurs in [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) through [`packages/storage/src/settings-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/settings-store.ts)
- **Runtime enforcement** uses `@maka/core/sandbox-boundary` with permission escalation for policy violations

## Frequently Asked Questions

### Where are Maka Desktop settings stored on disk?

Settings persist in [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) at the workspace root directory. The [`packages/storage/src/settings-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/settings-store.ts) module manages file I/O, schema versioning, and default value injection. Each workspace maintains independent settings, enabling different configurations for development and production environments.

### Can I switch between multiple model providers without restarting?

Yes. Changing `activeModel` via `window.maka.settings.update()` or the Models tab takes effect immediately for new chat sessions. Existing conversations continue with their originally selected model to maintain consistency. Create multiple provider entries and toggle between them as needed.

### What happens when a tool request exceeds sandbox permissions?

The Runtime Host intercepts the violation and emits a `sandbox_boundary_request` event. The Desktop UI surfaces this as a permission prompt through components in [`permission-response-guard.tsx`](https://github.com/apache/maka/blob/main/permission-response-guard.tsx). Users may approve the specific request temporarily, permanently update the sandbox policy, or deny the action—causing the tool to fail gracefully with an explanatory error.