Configuration

murasaki.config.ts (or .js / .mjs) at your project root describes your app's identity, window, and build settings:

import { defineConfig } from 'murasaki'

export default defineConfig({
  appId: 'app.murasaki.example',
  productName: 'Murasaki App',
  version: '0.1.0',
  icon: 'assets/icon.png',
  window: {
    title: 'Murasaki App',
    width: 1000,
    height: 700,
    backendCapabilities: ['api:POST:/api/documents'],
  },
  capabilities: ['dialog:openFile', 'clipboard:writeText'],
})

defineConfig returns the same object for type inference and validates declarative window labels/routes synchronously. There is nothing to await.

Top-level fields

about

Omit about to keep the operating system's compact standard About dialog. On macOS, declaring it opts into a native, customizable AppKit panel. Windows and Linux currently continue to use their standard metadata dialog.

about: {
  name: 'My App',
  width: 520,
  height: 680,
  paragraphs: [
    'A focused desktop workspace.',
    'Built with Murasaki.',
  ],
  paragraphSpacing: 16,
  details: [
    { label: 'Build', value: '15212' },
    {
      label: 'Commit',
      value: '332b2aefc',
      href: 'https://github.com/example/app/commit/332b2aefc',
    },
  ],
  buttons: [
    { label: 'Docs', href: 'https://docs.example.com' },
    { label: 'GitHub', href: 'https://github.com/example/app' },
  ],
},

External destinations are restricted to absolute, credential-free http, https, and mailto URLs. The application icon is resolved by macOS from the installed bundle, so the About panel uses the same masked icon as Finder and the Dock.

window

windows

window is the primary window with the reserved label main. Declare secondary windows in windows; each entry accepts the same shape except for the primary-only console option and gets its own route, initial visibility, and command allowlist:

window: {
  route: '/',
  capabilities: ['window:open', 'window:list', 'window:manage'],
  backendCapabilities: ['api:POST:/api/settings'],
},
windows: {
  settings: {
    route: '/settings',
    width: 720,
    height: 560,
    createOnLaunch: false,
    capabilities: [],
    backendCapabilities: ['api:GET:/api/settings'],
  },
},

Labels are 1–64 safe characters and main is reserved. Secondary windows use createOnLaunch: true by default and are created hidden. Set it to false to keep a declaration dormant until Node Main calls windows.create(label). The primary is always created on launch. Secondary windows inherit no top-level permissions. A secondary console field is rejected because that option controls the Windows backend console for the whole application. See Windows & permissions for lifecycle and renderer APIs.

webview

These settings apply to every native WebView in development and packaged macOS/Windows applications. Window-specific overrides are not supported.

webview: {
  userAgent: 'AcmeDesktop/1.4 Murasaki',
  incognito: true,
  proxy: {
    protocol: 'socks5',
    host: '127.0.0.1',
    port: 1080,
  },
},

Proxy URLs and authentication fields are deliberately unsupported: schemes, paths, user@host, usernames, passwords, and unknown proxy fields fail config validation. If a proxy requires credentials, configure it outside Murasaki or use a local unauthenticated forwarding proxy. Configuration is passed to Wry's native WebKit/WebView2 builder and is also validated by the Rust host.

Platform constraints:

• macOS proxy support uses Wry's mac-proxy feature and requires macOS 14 or newer. A configured proxy fails WebView startup explicitly on older macOS. Private sessions use WebKit's non-persistent data store.
• Windows proxy support uses WebView2 browser arguments. Custom User-Agent requires WebView2 86.0.616.0 or newer; private mode requires 101.0.1210.39 or newer. WebView2 ignores those settings on older runtimes.
• Linux development and packaged AppDir/AppImage/.deb builds pass these options to Wry/WebKitGTK. Test the behavior against the WebKitGTK version shipped by each target distribution.

Incognito controls local WebView persistence only. It does not anonymize network traffic, hide the client from a proxy/server, or make app-level Node data private. Murasaki isolates browser profiles by native window so cookies, storage, and workers do not cross per-window backend authority. The primary keeps the historical app profile. Secondary profiles persist on Windows/Linux and macOS 14+; macOS 11–13 uses isolated non-persistent stores. Session sharing between windows is therefore intentionally unsupported; use Main/API state for explicit sharing. See Security.

capabilities

Native renderer APIs are deny-by-default. Add only the commands your app uses; unknown permissions do not grant anything:

capabilities: [
  'app:quit',
  'autostart:read',
  'autostart:write',
  'dialog:openFile',
  'clipboard:readText',
  'clipboard:writeText',
  'notification:show',
  'shell:openExternal',
  'window:setTitle',
]

The complete typed list is NativeCapability. The primary window uses window.capabilities ?? capabilities ?? []; each secondary uses its own list or []. Grants are evaluated for the calling renderer, and off-origin pages cannot use the native bridge. Window management adds window:getLabel, window:open, window:list, and window:manage. Programmatic application shutdown requires app:quit; enabling the built-in updater grants it to the primary window for the verified restart handshake. Login startup is split into read and write authority: use autostart:read for status() and reserve autostart:write for settings UI that calls enable() or disable().

Use a structured NativeCapabilityGrant when a target-bearing command must be limited. deny takes precedence over allow; a trailing /** is the only wildcard form:

capabilities: [
  { permission: 'shell:openExternal', allow: { urls: ['https://example.com/help/**'] } },
  { permission: 'shell:showItemInFolder', allow: { paths: ['/Users/me/Documents/**'] } },
  { permission: 'window:manage', allow: { windows: ['settings', 'preview'] } },
  { permission: 'systemPermission:request', allow: { permissions: ['camera'] } },
  { permission: 'secureStorage:get', allow: { keys: ['account:*'] } },
  { permission: 'webview:writeCookies', allow: { urls: ['https://app.example.com/**'] } },
]

String grants remain unrestricted for compatibility. URL, path, key, window, and OS-permission scopes are validated while loading config and enforced again by the Rust host.

backendCapabilities

Renderer access to local Node resources is separately deny-by-default. The primary window uses window.backendCapabilities ?? backendCapabilities ?? []; secondary windows inherit nothing and use their own list or [].

backendCapabilities: [
  'main:src/backend/account.ts#loadAccount',
  'action:src/actions/save.ts#saveDocument',
  'api:POST:/api/documents/*',
  'updater:check',
  'events:sync.*',
  'diagnostics:renderer-error',
]

Resources match exactly unless the grant ends in one trailing *, which is a prefix wildcard. API resources include the uppercase method. Broad grants such as main:*, action:*, api:*, updater:*, and events:* are valid, but exact resources are safer for production. Native shutdown, activation, and window-control endpoints are not grantable to renderers. See Security.

systemPermissions

This config describes host-OS consent, not which renderer commands are trusted. For packaged macOS apps, Murasaki writes purpose text to Info.plist and can request most permissions at launch:

systemPermissions: {
  macOS: {
    camera: {
      usageDescription: 'Use your camera for video calls.',
      requestOnLaunch: true,
    },
    microphone: {
      usageDescription: 'Use your microphone for voice calls.',
    },
    screenRecording: { requestOnLaunch: false },
    accessibility: { requestOnLaunch: false },
    inputMonitoring: { requestOnLaunch: false },
    location: {
      usageDescription: 'Show nearby points of interest.',
      mode: 'whenInUse',
    },
    fullDiskAccess: { requestOnLaunch: false },
    photos: { usageDescription: 'Attach a photo to your post.' },
    contacts: { usageDescription: 'Find your friends.' },
    calendar: { usageDescription: 'See your schedule.' },
    reminders: { usageDescription: 'See your reminders.' },
    speechRecognition: { usageDescription: 'Transcribe your voice memos.' },
    bluetooth: { usageDescription: 'Find nearby devices.' },
    appleEvents: { usageDescription: 'Automate another app on your behalf.' },
    localNetwork: { usageDescription: 'Discover devices on this network.' },
  },
},

Prefer a contextual systemPermission.request() over launch-time prompts when the user can first understand the feature. Runtime calls additionally require systemPermission:status / systemPermission:request in that renderer's capability list. Windows unpackaged desktop consent is usage-driven, so it has no equivalent generic launch prompt; all fifteen permission kinds above are macOS-only, since Windows/Linux expose no OS-level equivalent of these TCC-gated prompts. Test macOS TCC behavior from a packaged app, not the terminal/Node identity used by murasaki dev.

Entitlements and the App Sandbox

Murasaki currently supports hardened-runtime signing, not the macOS App Sandbox. With sign.appSandbox left at its default false, Murasaki derives the Hardened Runtime resource-access entitlements for camera, microphone, location, photos, contacts, calendar/reminders, and Apple Events from systemPermissions.macOS. A signed build needs both those host entitlements and the corresponding Info.plist purpose strings. Bluetooth and speech recognition only need their purpose strings under this non-sandboxed posture. The bundled Node helper alone receives its hardened-runtime JIT rights; native add-ons receive no executable entitlement. sign.appSandbox: true is rejected fail-closed because Apple's inherited sandbox helper rules are incompatible with the current embedded Node/JIT architecture. Custom sign.entitlements and sign.helperEntitlements files are used verbatim, and configured paths must exist and pass plutil validation. See Native APIs → Entitlements and the App Sandbox for the full per-kind mapping.

main

Murasaki loads src/main.ts when it exists. Use main to choose another entry, change the graceful cleanup deadline, or disable Main discovery:

main: {
  entry: 'src/backend/main.ts',
  shutdownTimeoutMs: 15_000,
}
// main: false

See Node Main for lifecycle hooks and 'use main'.

protocols

Register custom URL schemes and receive matching URLs through Node Main's openRequested() hook:

protocols: [
  { scheme: 'violet', name: 'Violet Link' },
]

Duplicate or invalid schemes fail the build. macOS writes the registration into the packaged .app's Info.plist. Windows NSIS/MSI installers write the OS registration; a portable Windows archive does not. Linux writes the matching MimeType entries into the .desktop file; installing the .deb registers that file and refreshes the desktop database. A manually extracted AppDir or AppImage does not perform an OS-level registration step.

fileAssociations

Register one or more extensions as a document type:

fileAssociations: [
  {
    extensions: ['vnote', 'violet-note'],
    name: 'Violet Note',
    description: 'A note created with Violet',
    role: 'editor',
    mimeType: 'application/x-violet-note',
  },
]

Extensions must be unique across all entries; invalid extensions and MIME types fail the build. Matching files are delivered to Node Main's openRequested() hook. The same artifact limits as protocols apply: packaged macOS .app, installed Windows NSIS/MSI, and installed Linux .deb packages register the association. Portable Windows archives, manually extracted AppDir/AppImage artifacts, and murasaki dev do not install OS-level associations.

See Deep links and file associations for delivery semantics, testing, and untrusted-input requirements.

bundle

Server/Main code is compiled for production. Static bare npm imports are detected and staged automatically; use these options for dependencies and assets whose runtime behavior cannot be discovered statically:

bundle: {
  external: ['computed-plugin'],
  noExternal: ['small-js-only-package'],
  resources: [
    'prisma/schema.prisma',
    { from: 'prisma/migrations', to: 'database/migrations' },
    { from: 'bin/indexer', to: 'sidecars/indexer', executable: true },
  ],
}

Do not place secrets in resources; everything in an app bundle is readable by the user. Test native addons on every target architecture.

plugins

Use defineMurasakiPlugin to declare trusted build-time extensions. Plugins run with the same Node.js privileges as murasaki.config.ts; install only code you trust.

import { defineConfig, defineMurasakiPlugin } from 'murasaki'
import inspect from 'vite-plugin-inspect'

const assetsPlugin = defineMurasakiPlugin({
  name: 'acme.assets',
  vite: inspect(),
  bundle: {
    external: ['native-addon'],
    resources: [{ from: 'models', to: 'models' }],
  },
  hooks: {
    async before({ command, target, projectRoot, config }) {
      // Generate/check files before dev, build, or bundle.
    },
    async after(context) {
      // Runs serially after a successful command.
    },
  },
})

export default defineConfig({
  appId: 'app.murasaki.example',
  productName: 'Murasaki App',
  plugins: [assetsPlugin],
})

Hook context contains a deeply frozen configuration snapshot (without the plugin objects), absolute projectRoot, command (dev, build, or bundle), and the concrete target for bundle commands. Plugin objects and functions are never serialized into murasaki-meta.json.

This SDK extends the build pipeline only. It is not a native Rust ABI, a dynamic library loader, or a renderer/runtime plugin sandbox. Native features still belong in Murasaki's native host and capability model.

build

build: {
  before: 'pnpm --filter @acme/database build && pnpm prisma generate',
  envPrefix: ['MURASAKI_PUBLIC_', 'ACME_PUBLIC_'],
}

Only prefixed variables are client-public, but never put secrets under those prefixes: Vite replaces their values into shipped JavaScript.

Environment variables and .env

The Murasaki CLI automatically loads the following files from the project root. Later files have higher priority, while variables already supplied by the terminal or CI override every .env file.

.env
.env.local
.env.development          # murasaki dev
.env.development.local
.env.production           # build / bundle / installer
.env.production.local

Prefix renderer values with Murasaki's MURASAKI_PUBLIC_ namespace and read them through import.meta.env:

MURASAKI_PUBLIC_API_ORIGIN=https://api.example.com
ACCOUNT_API_TOKEN=keep-this-private

const apiOrigin = import.meta.env.MURASAKI_PUBLIC_API_ORIGIN

Unprefixed values never enter the renderer bundle. In murasaki.config.*, plugin hooks, Node Main, Server Actions, and API Routes, read them as ordinary Node environment variables:

const token = process.env.ACCOUNT_API_TOKEN

MURASAKI_PUBLIC_ values are embedded into shipped JavaScript at build time, so never use that prefix for secrets. Packaged Node Main inherits the launcher's environment, but Murasaki does not copy .env files into the app. For installed app secrets or end-user runtime settings, use the deployment environment, OS credential store, secureStorage, or context.paths.data.

security

Murasaki injects one environment-specific Content Security Policy into both the framework shell and a user-owned index.html. Configure a complete replacement, or explicitly opt out:

security: {
  csp: "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' https: wss:; object-src 'none'; base-uri 'none'; frame-src 'none'",
},

// Escape hatch when another layer owns the policy:
// security: { csp: false },

If index.html already contains a CSP <meta http-equiv> tag, Murasaki keeps that user-owned policy and moves it to the beginning of <head> so it applies before scripts or resources. Configure the policy in exactly one place: combining an existing tag with a security.csp string is a build error. Configured policies must be non-empty, single-line strings without control characters, double quotes, <, or >. See Security for defaults, migration guidance, and limitations of meta-delivered CSP.

updater

true is a complete, working setup for a normal OSS app — the GitHub repo is inferred from package.json's repository field, the public key from .murasaki/update-key.pub, channel defaults to 'stable', checked once at launch. The object form only needs to override what doesn't fit those defaults:

type UpdaterConfig =
  | boolean
  | {
      repo?: string                    // "owner/repo" — defaults to package.json#repository
      endpoint?: string                // self-hosted manifest URL — mutually exclusive with repo, must be https (loopback http allowed for local testing)
      channel?: string                 // release channel, default 'stable'
      checkOnStart?: boolean           // check once at launch, default true
      checkInterval?: string | false   // e.g. '6h' — re-check on a timer, default '6h'
      publicKey?: string               // base64 Ed25519 public key — defaults to .murasaki/update-key.pub
      publicKeys?: string[]            // additional pinned keys for rotation (max 4 total with publicKey)
      maxManifestAgeDays?: number      // reject a manifest older than this many days, default 90
      allowLegacyManifestsWithoutGeneratedAt?: boolean // migration escape hatch, default false
    }

There is deliberately no provider field — GitHub vs. self-hosted is inferred from whether repo or endpoint is set, so it can't drift out of sync with the rest of the config. There is also no way to disable signature verification, and a self-hosted endpoint must be credential-free https: (an http: endpoint is only accepted for loopback hosts — 127.0.0.1, localhost, [::1] — for local testing), enforced both here and again at fetch time. generatedAt is required by default for replay protection. The legacy escape hatch should only be enabled while migrating an older signed manifest.

checkOnStart and checkInterval are driven by the update engine itself, so they apply whether or not anything in your UI ever calls check(). You can still call useUpdate().check() by hand — an in-flight check is never started twice concurrently.

Consumed by useUpdate() and <UpdateButton /> (both from murasaki) — see the full Auto-update guide for the manifest format, signing, and publishing releases.

installer

macOS DMG styling and Windows NSIS/MSI installer options. Omit entirely to use Murasaki's defaults.

installer.windows

When the built-in updater is enabled, Windows distribution is intentionally NSIS per-user only: MSI generation is skipped and installMode: 'perMachine' is rejected. MSI remains available when updater is disabled for deployments managed through MSI major upgrades. The installer command fails if the required platform packaging tool produces no installer; use murasaki bundle when you only need the portable ZIP.

sign

Murasaki signs with your certificate/provider — it ships none of its own. Notarization credentials and PFX passwords are read from environment variables, never from this config — see Distribution → Signing.

macOS fields

sign.windows

murasaki bundle --sign --target win32-x64 signs the app executable before the portable ZIP is made. murasaki installer --sign --target win32-x64 also signs each generated installer (NSIS and, when the updater is disabled, MSI), then verifies every signature with the Authenticode policy. This step runs on Windows with SignTool.

All selectors also have CI environment overrides; see Windows installers and signing.

Next