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

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.

// 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. 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 at the workspace root. The storage layer in 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

// 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 and permission-response-guard.tsx
• Artifact Rendering — executes HTML output in constrained iframes using artifact-preview.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

// 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 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()

// 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 through 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 at the workspace root directory. The 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. 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.

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