Macos Sandbox App Data

---
name: macos-sandbox-app-data
description: >
  Locate, inspect, and safely edit config/data for sandboxed macOS apps that store
  state under ~/Library/Containers and ~/Library/Group Containers instead of an obvious
  config.yaml. Use when an App Store/Flutter/Electron app hides the active config behind
  bundle IDs, JSON controller files, runtime-generated profiles, or subscription-managed
  sources.
tags:
  - macos
  - app-sandbox
  - containers
  - config
  - troubleshooting
version: 1
---

Goal
- Find the real persistent config for a macOS app, not just the first YAML/JSON that looks plausible.
- Distinguish user-editable source files from generated runtime artifacts.
- Make edits in the durable layer that will survive app restart when possible.

Use when
- User says an app has custom rules/config but cannot find where it is stored.
- A macOS app from App Store/TestFlight/Flutter/Electron hides state behind a bundle ID.
- Searching for `config.yaml` in home directory returns nothing useful.
- The app appears to generate runtime YAML/JSON from a separate source profile.

Do not use when
- The app is clearly a plain CLI tool with config already in `~/.config`, `/etc`, or repo-local files.
- The target is an iOS device backup or mobile container, not local macOS app data.

Core model
Most sandboxed macOS apps split state across 3 layers:
1. App container
   - `~/Library/Containers/<bundle-id>/`
   - Often holds app-local caches, Documents, Preferences, and sandbox-private files.
2. Group container
   - `~/Library/Group Containers/group.<bundle-id>/`
   - Often holds shared app data, active profiles, logs, downloaded assets, or service state.
3. Generated runtime state
   - Files regenerated from a source profile or controller JSON.
   - Safe to inspect; often wrong place to edit.

Workflow
1. Identify the app bundle/process first.
   - `mdfind 'kMDItemFSName == "*Clash*"c'`
   - `ps aux | rg -i 'clash|mihomo|sing-box|bundle-id-fragment'`
2. Search likely container roots before broad home scans.
   - `find ~/Library/Containers -maxdepth 3 -iname '*bundle*'`
   - `find ~/Library/Group Containers -maxdepth 3 -iname '*bundle*'`
3. If the app is running, use open files as ground truth.
   - `lsof -p <pid> | rg -i 'yaml|yml|json|plist|profile|config|group containers|containers'`
4. Read controller files before editing anything.
   - Common names: `service.json`, `profiles.json`, `setting.json`, `storage.json`, `*.plist`
   - Look for keys like:
     - `core_path`
     - `current_id`
     - `runtime-profile-save-path`
     - `patch`
     - `url`
5. Classify candidate files.
   - Persistent source profile: user-editable, usually referenced by `core_path` or `current_id`
   - Runtime compiled profile: regenerated, often named like `runtime`, `final`, `patch_final`
   - Metadata/patch overlay: JSON controlling selection, subscriptions, or merge behavior
6. Edit the persistent source, not the generated runtime artifact.
7. Check overwrite risk before finalizing.
   - If profile metadata includes a remote `url` or auto-update flag, manual edits may be overwritten.
8. If the source profile is subscription-managed, look for a patch/overlay layer before telling the user to disable updates.
   - Check JSON/controller files for `profile_patchs.json`, `core_path_patch`, or `core_path_patch_final`.
   - If metadata is thin, inspect app strings for patch evidence:
     - `strings -a /Applications/<App>.app/... | rg 'profile_patch|overwrite-rules|overwrite-sub-rules|add_profile_patch|patch_board'`
   - If a YAML candidate only contains overlay keys such as `prepend`, `append`, or `delete` and lacks `proxies` / `proxy-providers`, do not import it as the main profile. Treat it as a patch layer and attach it to the real subscription/profile via the app's patch metadata.
   - In Clash Mi, `Invalid Clash Yaml file: proxies and proxy-providers not found` is the signature that a patch-only YAML was imported as if it were a full profile.
   - Prefer a no-overwrite patch layer for durable custom rules on top of the subscription when the app exposes one.
9. Verify after edit.
   - Re-read controller file and target profile path.
   - Confirm the app reloads or regenerates runtime config from the edited source.
   - If using a patch layer, confirm it attaches to the current subscription/profile instead of replacing the upstream source.
   - Check logs for permission or port-conflict errors if behavior does not change.

Fast commands
```bash
find "$HOME/Library/Containers" -maxdepth 4 \( -iname '*<app>*' -o -iname '*<bundle>*' \) 2>/dev/null
find "$HOME/Library/Group Containers" -maxdepth 4 \( -iname '*<app>*' -o -iname '*<bundle>*' \) 2>/dev/null
lsof -p <pid> 2>/dev/null | rg -i 'yaml|yml|json|plist|profile|config|group containers|containers'
rg -n 'core_path|current_id|runtime-profile-save-path|patch|url' "$HOME/Library/Group Containers/group.<bundle>"
```

Verification checklist
- Found the active bundle/container, not just a similarly named log file.
- Found the controller file that points to the live profile.
- Identified whether the target file is source or generated runtime.
- Checked whether subscription/update metadata can overwrite edits.
- Avoided reporting runtime artifacts as the primary edit target.

Pitfalls
- Broad `~/Library` searches on macOS trigger many `Operation not permitted` results; narrow scope early.
- Group container may hold the real config while app container only holds caches/preferences.
- A visible `runtime_profile.yaml` or `patch_final.json` is often generated output, not the durable source.
- Some apps store the active path only in JSON, so `config.yaml` searches miss the real target.
- App logs may reveal TCC issues like Full Disk Access requirements; this can block related service behavior.
- Subscription-managed profiles can revert manual edits on refresh.
- If the app has a patch board / overlay mechanism, advising `do not update` is usually second-best; prefer durable no-overwrite patches over hand-editing subscribed YAML.
- User-supplied rule lists may contain invalid Clash syntax like `DOMAIN,http://host:port/,DIRECT` or trailing `/` in `DOMAIN-SUFFIX`; normalize before recommending import.
- If the user gives only a rule overlay list (`prepend`/`append`/`delete`), do not tell them to import it as a standalone Clash config; wire it into the app's patch mechanism instead.

Support files
- `references/clash-mi.md` — concrete observed layout, patch hints, and edit targets for Clash Mi on macOS.