Skip to content

Configuration Files ​

All Mise configurations are stored in standard JSON and Markdown format within your user profile directory:

text
~/.config/mise-browser/

1. Engine & Preferences (config.json) ​

Controls hardware switches, process limits, privacy whitelists, and search preferences:

json
{
    "disable_gpu": false,
    "background_throttling": true,
    "process_limit": 4,
    "tab_sleep_timeout_minutes": 15,
    "sidebar_auto_collapse": true,
    "startup_behavior": "restore",
    "show_status_bar": true,
    "show_clock": true,
    "clock_format": "datetime",
    "show_window_controls": false,
    "email_handler": "system",
    "search_engine": "https://duckduckgo.com/?q=%s",
    "custom_search_aliases": {
        "aur": "https://aur.archlinux.org/packages?K=%s",
        "nix": "https://search.nixos.org/packages?query=%s",
        "mdn": "https://developer.mozilla.org/en-US/search?q=%s"
    },
    "spellchecker_language": "en-GB",
    "theme": "dark",
    "webview_theme": "dark",
    "theme_colors": {
        "dark": {
            "accent": "#7aa2f7",
            "bg_main": "#1a1b26",
            "bg_sidebar": "#16161e",
            "text": "#c0caf5",
            "sidebar_opacity": 100,
            "overlay_opacity": 100
        },
        "light": {
            "accent": "#6d3b09",
            "bg_main": "#e5e5e5",
            "bg_sidebar": "#d4d4d4",
            "text": "#1a1a1a",
            "sidebar_opacity": 100,
            "overlay_opacity": 100
        }
    },
    "enable_diagnostics": false,
    "webrtc_policy": "default_public_interface_only",
    "doh_provider": "off",
    "doh_custom_url": "",
    "allow_local_certificates": true,
    "allow_local_documents": false,
    "trusted_certificates": [],
    "filter_lists": {
        "easylist": true,
        "easyprivacy": true,
        "annoyances": false,
        "social": false,
        "custom_urls": []
    },
    "trusted_domains": [
        "x.com",
        "amazon.co.uk",
        "accounts.google.com",
        "google.com"
    ]
}

Options Description ​

Performance and Hardware Preferences

  • disable_gpu: Set to true to disable hardware GPU acceleration on systems with problematic graphics drivers.
  • background_throttling: Throttles timers and delays tasks in background tabs to conserve CPU cycles.
  • process_limit: Hard cap on Chromium renderer process forks (1 to 5).
  • tab_sleep_timeout_minutes: Inactivity timeout before background tabs detach and hibernate (5, 15, 30, 60, or 0 to disable).
  • sidebar_auto_collapse: When true, collapses the vertical sidebar into a 36px icon strip, expanding smoothly on hover or via shortcut.
  • startup_behavior: Startup launch behaviour (restore, dashboard, or new-tab). Defaults to restore (reopens on the exact active tab and workspace where you left off). When set to dashboard, Mise opens the Workspaces Dashboard overlay on launch for instant keyboard selection. When set to new-tab, Mise opens a fresh search tab on launch.
  • show_status_bar: When true, displays the 28px footer status bar with modal state, real-time link hover preview, centered address bar pill, and TLS security status.
  • show_clock: When true, displays a real-time clock and date widget in the status bar and sidebar for full screen browsing.
  • clock_format: Date and time display format: 12h (e.g. 02:45 PM), 24h (e.g. 14:45), seconds (e.g. 14:45:08), or datetime (e.g. 15 Oct, 14:45).
  • show_window_controls: When true, displays window action buttons (minimise, maximise/restore, close) at the top of the sidebar for desktop environments without native window decorations.
  • email_handler: Choose between system (OS default mailto:) or webmail providers (Gmail, Zoho, Outlook, Fastmail, ProtonMail).
  • search_engine: Fallback search provider URL when non-URL queries are entered without an alias.
  • spellchecker_language: Dictionary language used for input spellchecking (e.g. en-GB, en-US, en-CA, en-AU, cs, de, fr, es, it, pt, nl, pl, or disabled).
  • theme: Interface theme preference (dark for Tokyo Night or light).
  • webview_theme: Website native theme preference (dark or light), toggled via the sidebar theme button.
  • allow_local_certificates: When true (default), permits connections to self-signed TLS certificates on private subnets and local endpoints (192.168., 10., 172.16-31.*, localhost, .local) for home servers, Cockpit, Proxmox, TrueNAS, and routers.
  • allow_local_documents: When true, permits viewing local documents (.html, .htm, .xhtml, .txt, .svg, .pdf) on demand. Kept false by default to uphold Zero-Trust local filesystem isolation, restricting access to safe user directories whilst rejecting sensitive system paths (/etc, /proc, /sys), hidden credential stores, and executable scripts.
  • trusted_certificates: Array of host and port endpoints explicitly permitted to bypass TLS certificate verification (e.g. ["192.168.1.61:9090"]).
  • filter_lists: Object configuring active adblocking and tracker filter list subscriptions:
    • easylist: Enables core EasyList ad and banner blocking rules (default: true).
    • easyprivacy: Enables EasyPrivacy tracker and analytics blocking rules (default: true).
    • annoyances: Enables uBlock and EasyList annoyances rules for cookie notices and popups (default: false).
    • social: Enables Fanboy social media widget blocking rules (default: false).
    • custom_urls: Array of custom HTTPS community filter list URLs.
  • theme_colors: Custom visual colour palette and opacity settings per theme mode:

Appearance and Visual Theme Preferences

  • accent: Primary highlight colour for active tabs, borders, and controls (defaults to #7aa2f7 in dark, #6d3b09 in light, with curated mode-tailored preset palettes including neutral washed out white, light grey, and black tones).
  • bg_main: Base window and modal canvas background colour.
  • bg_sidebar: Vertical sidebar background colour.
  • text: Primary text and icon foreground colour.
  • sidebar_opacity: Sidebar background translucency percentage (40% to 100%) with backdrop blur glass effect.
  • overlay_opacity: Modal and overlay translucency percentage (50% to 100%) for Command Palette, Notes, and Preferences.
  • enable_diagnostics: When true, enables local in-memory diagnostic ring buffer recording for auditing and issue reproduction (OFF by default for zero telemetry).
  • webrtc_policy: WebRTC IP leak protection policy (default_public_interface_only, disable_non_proxied_udp, disable, or default_public_and_private_interfaces). Defaults to default_public_interface_only to eliminate local network IP leakage while maintaining VoIP functionality. Use disable_non_proxied_udp when routing through VPNs or proxies.
  • doh_provider: Active DNS-over-HTTPS provider (off, quad9, mullvad, cloudflare, or custom). Disabled by default (off), relying on the host operating system's standard resolver.
  • doh_custom_url: Custom HTTPS endpoint URL for DNS resolution when doh_provider is set to custom (e.g. https://dns.example.com/dns-query). Must use the https:// scheme and remain within 512 characters.
  • trusted_domains: Array of domains exempted from tracker blocking and fingerprint spoofing.
  • external_notes_command: Optional command or executable used to open notes and clippings (e.g. obsidian, logseq, code, nvim). When empty, uses system default Markdown handler. Path resolution is strictly confined to the application configuration directory, safeguarding against directory traversal. Modifying this setting via the interface or IPC triggers an interactive native confirmation prompt before persisting to disk.
  • custom_search_aliases: Key-value map of custom search prefixes and URL templates (with %s query placeholder). Typing <alias> <query> in the address bar (such as aur hyprland or gh mise) bypasses fallback engines and routes queries straight to the destination. Users can configure, override, or extend default built-ins directly in Preferences.

2. Keybindings Map (keybinds.json) ​

Maps internal browser actions to custom keystroke combinations. See the Keyboard Shortcuts Reference for the complete list of action names.


3. Session State (session.json, session.json.bak, session_sentinel.json) ​

Maintains persistent workspaces, URLs, titles, Dark Reader preferences, and sleeping tab scroll offsets across restarts:

json
{
    "current_workspace": "Work",
    "workspaces": {
        "Work": [
            "https://github.com/notifications"
        ],
        "Personal": [
            "https://archlinux.org"
        ]
    },
    "active_tabs": {
        "Work": 0,
        "Personal": 0
    },
    "tab_titles": {
        "Work": ["Notifications"],
        "Personal": ["Arch Linux"]
    },
    "tab_sleep_states": {
        "Personal": [
            {
                "url": "https://archlinux.org",
                "title": "Arch Linux",
                "scrollX": 0,
                "scrollY": 840,
                "hibernatedAt": 1727299000000
            }
        ]
    },
    "tab_dark_reader": {
        "Work": [true],
        "Personal": [false]
    },
    "tab_pinned": {
        "Work": [true],
        "Personal": [false]
    },
    "tab_favicons": {
        "Work": ["https://github.com/favicon.ico"],
        "Personal": ["https://archlinux.org/favicon.ico"]
    },
    "workspace_visuals": {
        "Work": {
            "color": "#9ece6a",
            "glyph": "💼"
        },
        "Personal": {
            "color": "#7aa2f7",
            "glyph": "1"
        }
    }
}

Session Files & Atomic Resilience ​

  • session.json: The primary session state file. To prevent data corruption during sudden system shutdowns or power cuts, Mise writes updates to a temporary file (session.json.tmp) and swaps it via an atomic POSIX rename operation. Contains persistent tab URLs, active tab indices, titles, dark reader preferences, pinned tabs, and workspace_visuals (custom accent colours and single-character glyph badges per workspace). Visual identities for the volatile Private profile are filtered out on disk.
  • session.json.bak: A rolling backup journal automatically updated before every primary session flush. If session.json is missing or corrupted, Mise automatically recovers the previous state from this journal.
  • session_sentinel.json: A lifecycle sentinel file recording whether the previous browser process terminated cleanly ("clean_exit": true). If an abrupt crash, kill signal, or power failure occurs, the sentinel detects clean_exit: false on startup, engages crash recovery mode, forces background tabs to sleep to avert memory spikes, and displays a status bar notice.

4. Bookmarks & Quickmarks ​

  • bookmarks.json: An array of saved bookmark objects containing title, url, and creation timestamp.
  • quickmarks.json: A key-value dictionary mapping single alphanumeric keys to URLs (e.g. "g": "https://github.com").

5. Quick Notes (notes.md) & Clippings ​

  • notes.md: A standard Markdown file storing everything typed into the Quick Notes overlay (Ctrl + N) or exported from Reader View (Ctrl + Shift + E). You can edit this file directly or open it from the overlay in your favourite external editor (Obsidian, Logseq, Neovim, VS Code).
  • clippings/: Dedicated directory storing standalone exported Markdown clippings and distilled articles saved for external note tools.

6. Permissions Vault (permissions.json) ​

Maintains persistent hardware and sensor permissions per domain for non-private workspaces:

json
{
    "github.com": {
        "clipboard-read": "prompt",
        "notifications": "denied"
    },
    "meet.google.com": {
        "media": "granted",
        "geolocation": "denied"
    }
}
  • Sensors Managed: Media (camera and microphone), geolocation, notifications, and clipboard access.
  • Security Boundaries: Written atomically to ~/.config/mise-browser/permissions.json with strict 0600 POSIX file permissions. Private workspaces bypass this file completely, operating under an unconditional Zero-Trust lockdown where all hardware sensor requests are blocked.

Released under the GNU General Public Licence v3.0. • Follow on Mastodon • Discuss on Reddit