File Locations

Kumo centralizes paths in KumoPaths, so the GUI, the CLI, the tests, and the planned service mode all agree on where things live.

Root

~/Library/Application Support/Kumo/

Print this from the CLI:

kumo config list

Directory layout

Kumo/
  profiles/
    default.yaml              # Disposable; regenerated when missing.
    profiles-metadata.json    # Profile metadata index.
    current.txt               # Active profile id.
  overrides/
    overrides.json            # Ordered override list.
    files/                    # Per-override YAML / JS / log files.
  work/
    config.yaml               # Generated Mihomo runtime configuration.
    core.pid                  # PID file for the running Mihomo core.
  logs/
    core.log                  # Mihomo stdout + stderr.
    substore.log              # Sub-Store backend stdout + stderr.
    cli/                      # Per-invocation kumo debug logs.
    app-update-installer.log  # Detached DMG installer log.
  cores/
    mihomo                    # Managed Mihomo binary (when installed).
  substore/
    status.json               # Sub-Store backend status & connection config.
    resources/
      manifest.json
      node/bin/node
      backend/sub-store.bundle.js
    data/                     # Sub-Store runtime data.
    temp/                     # Sub-Store staging work.
  updates/
    downloads/                # App update download cache.
  proxy-geo-cache.json        # Country lookups, 30-day TTL.
  state.json                  # Shared state used by GUI and CLI.
  preferences.json            # App-level preferences.

Top-level files

state.json

Stores the runtime state shared between GUI and CLI:

• Core run state and process id.
• Outbound mode (rule / global / direct).
• Controller endpoint and mixed proxy port.
• System proxy state, including PAC mode and pacScript.
• Controlled runtime settings (TUN stack, routing, DNS, route exclusions, MTU, ICMP forwarding).
• Last status message.

Decoding tolerates missing fields, so a Kumo update can add new keys without invalidating an older state.json.

preferences.json

UI lifecycle preferences only:

• launchAtLogin (kept in sync with SMAppService.mainApp).
• hideMenuBarIcon.
• quitOnLastWindowClose.
• updateChannel (stable / beta).
• updateManifestURL (optional override).

Decoding falls back to defaults, so a missing or corrupted file never blocks launch.

work/config.yaml

The merged runtime configuration Mihomo actually reads. Generated from the active profile, enabled overrides, and Kumo-controlled keys. Editing this file directly has no lasting effect — it is regenerated on every start. Use overrides instead.

proxy-geo-cache.json

Caches ipwho.is lookups used for proxy-node flag resolution. 30-day TTL, 5-minute cooldown on failures. Safe to delete; the cache rebuilds itself in the background.

Backups

kumo backup export <path> writes a directory at <path> containing:

manifest.json
profiles/
overrides/
substore/
state.json

The first-format backup is directory-based rather than zip-based on purpose: it stays transparent, easy to diff, and easy for agents to inspect. A future UI may wrap the same manifest in a compressed archive or sync it to WebDAV without changing the import/export contract.

Restore with kumo backup import <path>.

Reset

To wipe local Kumo state during development:

make reset-local-state

(That is a make target inside the KumoApp repo. It deletes ~/Library/Application Support/Kumo/ entirely.)