Chapter 2: Custom Recipes for Niche Apps¶

While ATBClone comes with 33+ pre-configured recipes for popular social, development, and browser applications, you may want to clone an unlisted or niche application (such as internal company software, indie developer tools, or regional messaging clients).

This chapter explains how to create custom recipes using the built-in App Prober and Recipe Editor, and details what each basic configuration parameter means.

📑 Table of Contents¶

• Understanding App Recipes
• Method 1: Using the Intelligent App Prober (Recommended)
• Method 2: Using the Visual Recipe Editor
• Basic Parameters Reference
• 1. bundle_id (Bundle Identifier)
• 2. app_name (Application Name)
• 3. strategy (Cloning Strategy)
• 4. strip_sandbox (Sandbox Stripping)
• 5. proxy (Proxy Settings)
• 6. injection_strategy (Injection Strategy)
• Sample Custom Recipe YAML
• Next Steps

🧩 Understanding App Recipes¶

An App Recipe is a declarative blueprint that instructs ATBClone how to handle an application:

• Which cloning engine to use (Hard Clone vs. Soft Clone).
• How to isolate user data (e.g., via $HOME environment hijack or --user-data-dir CLI flags).
• Whether to strip Apple App Sandbox entitlements.
• What system folders (like Keychain credentials) should remain bridged.

All user custom recipes are saved as human-readable .yaml files in: ~/ATBClone/recipes/<bundle_id>.yaml

Whenever you clone an app, ATBClone checks your custom recipes first, giving them priority over built-in presets.

🔍 Method 1: Using the Intelligent App Prober (Recommended)¶

The App Prober is ATBClone's built-in binary inspection tool. It inspects Mach-O binary architectures, detects runtime frameworks (Electron, Chromium, Gecko, Cocoa), scans code signatures, and automatically generates the optimal recipe.

+-------------------------------------------------------------+
|  🔍 App Prober                                              |
|                                                             |
|  Target Application:                                        |
|  [/Applications/CustomTool.app               ] [ Browse... ]|
|                                              [ Start Probe ]|
|  ─────────────────────────────────────────────────────────  |
|  Analysis Results:                                          |
|  • Application: CustomTool                                  |
|  • Bundle ID:   com.example.customtool                      |
|  • Sandbox:     Enabled (App Sandbox Detected)              |
|  • Frameworks:  Electron, Node.js                           |
|  • Strategy:    hard_clone                                  |
|                                                             |
|  [ Save as Recipe 💾 ]                                      |
+-------------------------------------------------------------+

Step-by-Step Workflow:¶

1. Click "App Prober" (🔍) in the ATBClone sidebar navigation.
2. Click "Browse..." and select your niche .app bundle.
3. Click "Start Probe".
4. The Prober analyzes the application structure in milliseconds and displays:
5. App Name & Bundle ID: Extracted from Info.plist.
6. Sandbox Status: Checks if com.apple.security.app-sandbox is enforced.
7. Embedded Frameworks: Detects Electron, Chromium Embedded Framework (CEF), Qt, Flutter, React Native, or Native Cocoa.
8. Recommended Strategy: Determines whether hard_clone or soft_clone is optimal.
9. Click "Save as Recipe 💾".

Once saved, the recipe is immediately registered into your local library. You can now launch the "+ New Clone" wizard and clone the app with full isolation support!

✏️ Method 2: Using the Visual Recipe Editor¶

If you prefer to manually craft or fine-tune a recipe:

1. Click "Recipes" (📑) in the sidebar navigation.
2. Click the "+ New Recipe" button on the top right.
3. Fill in the basic configuration fields:
4. Bundle ID: e.g., com.company.internalapp
5. Application Name: e.g., InternalApp
6. Strategy: hard_clone or soft_clone
7. Strip Sandbox: Toggle on/off
8. Proxy Settings: Enable dedicated proxy if needed
9. Click "Save Recipe".

You can also click "Edit" on any existing built-in or custom recipe in the table to create an override copy.

📖 Basic Parameters Reference¶

Below is a detailed guide to all fundamental recipe parameters:

1. bundle_id (Bundle Identifier)¶

• Type: string (e.g., com.tencent.xinWeChat, com.google.Chrome)
• Description: The unique reverse-DNS identifier defined in the app's Info.plist. This is the primary lookup key used by ATBClone to match recipes.

2. app_name (Application Name)¶

• Type: string (e.g., WeChat, Telegram, Cursor)
• Description: The human-readable title of the application shown in the ATBClone interface.

3. strategy (Cloning Strategy)¶

• Type: enum (hard_clone | soft_clone)
• Description: Determines the underlying engine used to create and isolate the clone.

4. strip_sandbox (Sandbox Stripping)¶

• Type: boolean (true | false, default: false)
• Description: Controls whether ATBClone should extract and remove <key>com.apple.security.app-sandbox</key> from the app's code signing entitlements during Hard Clone creation.

5. proxy (Proxy Settings)¶

• Type: object
• Description: Defines a default network proxy configuration for instances created with this recipe.

proxy:
  enabled: true       # boolean: true or false
  type: http          # enum: "http", "https", or "socks5"
  host: 127.0.0.1     # string: proxy server IP address or hostname
  port: 7890          # integer: proxy server port

6. injection_strategy (Injection Strategy)¶

• Type: enum (auto | dylib | launcher, Default: auto)
• Description: Configures the underlying environment isolation technique for hard_clone operations.

📄 Sample Custom Recipe YAML¶

Here is what a complete custom recipe file looks like:

# ========================================================
# ATBClone Custom Recipe - ExampleApp
# Saved at: ~/ATBClone/recipes/com.example.app.yaml
# ========================================================

bundle_id: com.example.app
app_name: ExampleApp
strategy: hard_clone
app_type: cocoa
strip_sandbox: false
injection_strategy: auto

proxy:
  enabled: false
  type: http
  host: 127.0.0.1
  port: 7890

⏭️ Next Steps¶

• To understand how environment_injection, launch_args, and symlink_whitelist work in deep isolation scenarios, continue to Chapter 3: Under the Hood & Advanced Parameters.
• For common questions, diagnostics, and issue reporting, visit Chapter 4: FAQ & Diagnostic Troubleshooting.