Sub-Store hosting

Host your own Sub-Store backend, custom output formats, and how Kumo talks to it.

The Sub-Store user guide covers the bundled backend that ships with Kumo. This page is for pointing Kumo at a different Sub-Store instance — for example one running on a NAS, a VPS, or in a Docker container — and sharing it across devices.

Bundled backend

When Sub-Store is opened in Kumo for the first time, Kumo:

Copies the bundled Node.js binary and sub-store.bundle.js into ~/Library/Application Support/Kumo/substore/resources/.
Starts Node with that bundle, listening on a random localhost port.
Writes the chosen port and a randomly-generated token into ~/Library/Application Support/Kumo/substore/status.json.
Embeds the Sub-Store web UI in the native panel, pointed at that local port.

The backend lifecycle (start, stop, restart) is exposed through kumo substore.

Custom backend

To point Kumo at an existing Sub-Store instance:

Open Settings → Sub-Store.
Switch the source from Bundled to Custom.
Paste the backend URL (for example http://nas.local:3000).
Paste the access token if the backend has one.
Save.

Kumo stops the bundled backend on this Mac and points the embedded UI at the custom URL. The status card in the Sub-Store destination shows which mode is active.

Custom backend requirements

Reachable from the Mac (Bonjour, local network, VPN, or public internet — Kumo does not care).
Speaks the standard Sub-Store API.
Trusts the access token provided.

Custom backends are not auto-prepared by Kumo. Updating, securing, and backing up the data on the server is the user's responsibility.

Output formats

Sub-Store can output combinations in several formats:

Format	When to use it
ClashMeta	Default. The output Kumo Mihomo core understands.
Clash	For older Clash-compatible clients. Kumo also accepts it.
Surge	For Surge / Stash.
Quantumult X	For QX.

When pasting a Sub-Store URL into Kumo, append ?target=ClashMeta if the share URL does not already specify a target. Forcing ClashMeta gets the richest feature set (proxy providers, rule providers, etc.).

Force a rebuild

By default Sub-Store caches the combined output for a few minutes. If a combination was just edited and Kumo needs to see the new version immediately, hit Refresh on the Kumo profile that points at the combination, and append &noCache=true to the URL on the first refresh.

Lifecycle commands

kumo substore status --json       # is it running? which mode? which port?
kumo substore prepare             # copy bundled resources to ~/Library/...
kumo substore start
kumo substore stop
kumo substore restart

prepare runs automatically the first time Sub-Store is opened in the GUI, so it is usually not needed by hand. It is safe to run again — it overwrites the bundled resources with whatever shipped in the current Kumo version, useful after a Kumo update.

Backups

kumo backup export includes the Sub-Store data directory. Restoring a backup brings subscriptions and combinations back.