Configure moshi-hook Settings

Every persistent moshi-hook setting, including its default, tradeoffs, and when a daemon restart is required.

moshi-hook keeps a small set of host-level settings for background work, notifications, and Browser Preview discovery. List the current values and config path at any time:

moshi-hook set

Use kebab-case names with the CLI. Boolean settings accept on and off; the config file stores their snake-case equivalents under [gateway].

Settings at a glance

Setting	Default	Restart?	What it controls
`always-on-discovery`	`on`	Yes	Keeps looking for local dev servers and simulators when no phone is attached.
`usage-collection`	`on`	Yes	Polls local agent rate-limit data and syncs snapshots to Moshi.
`suppress-nested-agent-push`	`off`	Yes	Drops events from agents launched by another agent, including their approvals.
`suppress-push-while-unlocked`	`off`	Yes	On macOS, makes visible agent pushes silent while the console is unlocked.
`scan-ports`	`all`	No	Limits which loopback listeners Browser Preview may probe with HTTP.

Boolean changes are read when the daemon starts. After changing one, restart the service for your platform:

brew services restart moshi-hook                 # macOS / Homebrew
systemctl --user restart moshi-hook.service      # Linux / systemd

If you run moshi-hook serve yourself, stop and start that process instead. A scan-ports change applies on the next discovery refresh without a restart.

Background discovery

Keep discovery running even when a phone is not currently attached:

moshi-hook set always-on-discovery on

Turn it off to pause those idle server and simulator scans. Discovery still runs when Moshi actively subscribes, but the first result after reconnecting may take a refresh cycle.

Usage collection

Background usage collection keeps the usage rings in Moshi current:

moshi-hook set usage-collection on

Turn it off to stop background rate-limit polling and snapshot uploads from this host:

moshi-hook set usage-collection off

On-demand moshi-hook usage still reads local snapshots, and moshi-hook usage --sync can still upload them explicitly. See Agents & Usages.

Nested-agent events

An agent can launch another supported agent as a child process. To keep those nested runs out of Moshi:

moshi-hook set suppress-nested-agent-push on

This suppresses the nested agent's event entirely—not just its notification banner. Its inbox updates, completion events, and approval requests will not reach the phone. Leave this off if a nested agent may stop and wait for your approval.

Silent push while a Mac is unlocked

On macOS, keep agent events flowing to the inbox while silencing visible notification banners whenever the local console is unlocked:

moshi-hook set suppress-push-while-unlocked on

This affects visible approval, completion, and error pushes. The event is still published to Moshi; only its notification is marked silent. Lock state is only a signal that the Mac is unlocked, not proof that somebody is looking at it, so the setting is off by default. If macOS lock state cannot be read, moshi-hook leaves the push enabled.

Browser Preview ports

By default, Browser Preview considers every eligible loopback listener and uses conservative heuristics to avoid probing unrelated services:

moshi-hook set scan-ports all

Restrict discovery to ports you trust as HTTP servers:

moshi-hook set scan-ports 3000,5173,8000

An explicit list is authoritative, so it can include high-numbered ports that broad discovery would normally skip. Only loopback-reachable listeners are eligible. Disable HTTP probing completely with:

moshi-hook set scan-ports none

This only controls Browser Preview's HTTP probes; it does not stop the underlying processes or change which addresses they bind. See Browser Preview for the app-side workflow.

First-run prompt

The standalone Linux installer offers always-on-discovery and usage-collection during setup, with both selected by default. Reopen that prompt manually with:

moshi-hook set --first-run

Homebrew does not run an installer prompt. The defaults apply until an interactive host setup, serve, pair, or install command offers it, or until you run set --first-run yourself.

Edit the config file directly

The CLI preserves comments and unrelated keys in ~/.config/moshi/config.toml. The equivalent configuration is:

[gateway]
always_on_discovery = true
usage_collection = true
suppress_nested_agent_push = false
suppress_push_while_unlocked = false
scan_ports = "all"

For a fixed Browser Preview allowlist, use a TOML integer array such as scan_ports = [3000, 5173, 8000]. An empty array disables HTTP probing, just like moshi-hook set scan-ports none.

Persistent settings above are different from command flags. The daemon also accepts moshi-hook serve --gateway-listen <address> to override its local gateway bind address for that run. Every command accepts --verbose for debug logs and --base-url for a non-default Moshi API endpoint. Run moshi-hook <command> --help for that command's complete one-shot flag list.

Hook settings