中文版 English | 🌐 Online Docs | 📖 User Guide (EN) | 用户使用手册 (中文)

ATBClone (macOS Application Cloning Engine)

🚀 ATBClone is a modern application multi-instancing and clone management engine designed for macOS. It supports isolated user data directories, independent network proxies (HTTP / SOCKS5), automated recipe matching, ad-hoc code re-signing, and sandbox removal.

> 📖 Looking for a beginner-friendly tutorial? Visit our online documentation at clone.aitobox.com, or check out the English User Manual | 中文使用手册.

ATBClone Clones Dashboard

📥 Download

Visit the GitHub Releases page to download the latest release of ATBClone.

ATBClone provides two distribution packages with identical core functionality:

| Distribution Package | Target Audience | Description | | :--- | :--- | :--- | | ATBClone-arm-x.x.x.dmg | 👶 General Users (Strongly Recommended) | macOS Native GUI desktop application installer (.dmg). Provides a modern, visual card-based interface with zero terminal knowledge required. | | ATBCloneCli.tar.gz | ⚡ Power Users / Developers | Standalone binary command-line tool archive (ATBCloneCli). Zero Python dependencies required; ideal for terminal power users, automation scripts, and CI/CD pipelines. |

💡 User Guidance:

- Beginners / Everyday Users: Please prioritize downloading and using the GUI app (.dmg). It offers an intuitive visual interface for one-click cloning, app launching, status monitoring, and settings.

- Advanced Users / Developers: Use the CLI tool (ATBCloneCli / atbclone) for fast terminal interaction, batch scripting, deep application probing, and headless workflows.

✨ Key Features

📦 Dual-Engine Cloning Mechanism:

- Hard Clone: Designed for native and social applications (WeChat, QQ, Telegram, AI clients, Chrome, Edge, Arc, etc.). Duplicates the entire App Bundle, modifies Info.plist and Bundle Identifier, injects isolated HOME / TMPDIR data directories via in-process dynamic library injection (libatbclone_env.dylib) or Mach-O binary launcher hijack, optionally strips App Sandbox restrictions, and performs ad-hoc code re-signing. - Soft Clone: Designed for modern code editors and browsers (Cursor, VS Code, Firefox, Brave, Tor, Zed, etc.). Generates a lightweight wrapper bundle, automatically injecting isolated --user-data-dir / --profile launch arguments and proxy environment variables.

🔍 Intelligent App Prober: Automatically inspects Mach-O architectures, frameworks, and code signing sandbox entitlements for any application without a pre-configured recipe, dynamically determining the optimal soft/hard clone strategy and generating recommended recipes.
🌐 Isolated Network Proxies: Configure dedicated HTTP or SOCKS5 proxies (with authentication support) per cloned application without interfering with host system or primary application traffic.
📑 Recipe Engine: 34+ built-in recipes for popular apps and AI Agent tools, with local override support via ~/ATBClone/recipes/.
🪄 Interactive Wizard: Step-by-step interactive CLI guide supporting terminal drag-and-drop application paths, automatic name incrementing, custom data directory configuration, and on-the-fly proxy setup.
🔄 Lifecycle Management: View cloned apps (list), re-clone after primary app updates while preserving user and chat data (update), and safely remove clones with interactive prompts or flag controls (remove with --with-data / --keep-data).
🛡️ Security & Privilege Elevation: Writing to ~/ATBClone/Apps requires no admin privileges; writing to /Applications uses native single-prompt macOS osascript authorization; robust path escaping via shlex.quote throughout.

🖥️ Graphical User Interface (GUI — Recommended for General Users)

💡 Tip for Everyday Users: If you prefer not to use the terminal, download ATBClone-arm-x.x.x-arm.dmg from GitHub Releases, open the DMG, drag ATBClone.app to your Applications folder, and launch it directly.

The native macOS desktop interface provides a visual, streamlined experience:

Dashboard & Clone Cards:

- Displays all cloned applications in a modern card layout showing app icons, cloning strategies, proxy statuses, and creation timestamps. - Launch cloned apps, update after primary app upgrades (preserving chat history and data), or safely remove clones with a single click.

Visual Clone Creation:

- Drag and drop or browse for any .app bundle from your system. - Automatically matches built-in recipes or runs the App Prober on unlisted applications. - Customize clone name, display title, custom icon, dedicated data directory (e.g. on external SSDs), and independent HTTP / SOCKS5 proxies.

Built-in Recipe Library:

- Explore 34+ pre-configured application recipes (WeChat, QQ, Chrome, Cursor, ChatGPT, Claude, etc.) categorized by type, complete with sandbox stripping rules and isolation strategies.

App Prober (Deep Architecture Inspection):

- Inspect any unknown macOS app's Mach-O architecture, frameworks, and sandbox entitlements, and generate custom recipe YAML files with one click.

System Diagnostics (Doctor):

- Self-check system prerequisites, Xcode command-line tools, codesigning utilities, and storage permissions to ensure optimal stability.

Multi-language & System Tray:

- Fully localized across multiple languages (English, 简体中文, 繁體中文, 日本語, 한국어, Deutsch, Français, Русский, Español) with macOS menu bar tray integration.

(For developers running the GUI from source: run bash scripts/run_gui.sh or python -m atbclone.gui)

🚀 Command Line Interface (CLI — For Power Users & Scripting)

⚡ For Advanced Users & Automation: The CLI tool (atbclone or standalone binary ATBCloneCli) provides full control over the cloning engine with scriptable commands, rich terminal tables, and automation support.

1. Interactive Wizard (CLI Guided Mode)

No need to memorize CLI options—follow the interactive prompts in your terminal:

atbclone wizard

Workflow: Drag and drop .app path ➔ Auto-match recipe ➔ Set clone name ➔ Set display name and icon ➔ Select destination directory ➔ Custom data directory (if supported) ➔ Optional proxy setup ➔ Confirm and create.

2. Command Line Quick Clone (`clone`)

Basic Clone (Auto-incremented name, defaults to `~/ATBClone/Apps`)

atbclone clone /Applications/WeChat.app

Specify Clone Name and Output Directory

atbclone clone /Applications/WeChat.app --name "WeChat-Work" --output-dir ~/ATBClone/Apps

Custom Data Storage Directory (`--data-dir`)

For applications that support data isolation (Chromium series, Firefox, WeChat, etc.), you can specify a custom data storage directory (e.g. on an external SSD or dedicated workspace):

atbclone clone /Applications/Chrome.app --name "Chrome-Custom" --data-dir /Volumes/ExternalSSD/ChromeData

Note: The prober automatically detects if the application supports data isolation; attempting to set --data-dir on unsupported applications (e.g. Zed) will fail with a friendly error.

Clone Applications without Pre-configured Recipes (Auto-triggers Prober)

When cloning an app without a built-in recipe, ATBClone automatically runs App Prober to inspect the architecture and sandbox entitlements, dynamically generates the optimal recipe, and executes the clone:

atbclone clone /Applications/ATBCmder.app --name "ATBCmder-Work"

Configure Dedicated Network Proxies (HTTP / SOCKS5)

# Configure HTTP proxy with credentials (passwords stored securely in macOS Keychain)
atbclone clone /Applications/Telegram.app \
  --name "Telegram-Proxy" \
  --proxy-host 127.0.0.1 \
  --proxy-port 7890 \
  --proxy-type http \
  --proxy-user alice \
  --proxy-password "my_secret_token"
Configure SOCKS5 proxy
atbclone clone /Applications/ChatGPT.app \
  --name "ChatGPT-US" \
  --proxy-host 127.0.0.1 \
  --proxy-port 1080 \
  --proxy-type socks5

Injection Strategy Selection (`--injection-strategy`)

For Hard Clone apps, customize how isolated environment variables (HOME, TMPDIR, proxies) are injected into the cloned application:

# Auto mode (default): probes Mach-O load command headroom, prefers in-process dylib injection, falls back to launcher if headroom < 56 bytes
atbclone clone /Applications/WeChat.app --injection-strategy auto
Force dylib injection (guarantees native macOS system notifications and Menu Bar status icons)
atbclone clone /Applications/WeChat.app --injection-strategy dylib
Force Mach-O binary launcher hijack
atbclone clone /Applications/Chrome.app --injection-strategy launcher

Options: auto (default/recommended), dylib (in-process dynamic library, Darwin PIDVersion preserved), launcher (C binary launcher hijack).

3. List Cloned Applications (`list`)

View all clones managed by ATBClone in a Rich-formatted table:

atbclone list

Example output:

┏━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 名称     ┃ 原 APP  ┃ Bundle ID            ┃ 策略       ┃ 创建时间         ┃ 代理                   ┃
┡━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 微信2    │ 微信    │ com.tencent.xinWeChat │ hard_clone │ 2026-08-18 22:30 │ 未开启                 │
│ TG-Proxy │ Telegram│ ru.keepcoder.Telegram │ hard_clone │ 2026-08-18 22:45 │ http://127.0.0.1:7890  │
│ Chrome2  │ Chrome  │ com.google.Chrome    │ hard_clone │ 2026-08-18 23:00 │ 未开启                 │
└──────────┴─────────┴━━━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━━━━━┘

4. Synchronize Clones After Primary App Updates (`update`)

When the primary application is updated via the Mac App Store or website, update your clone with a single command while preserving all chat history, logins, and data:

atbclone update WeChat2

5. Remove Clones (`remove`)

Interactive Removal (Recommended)

When executing remove in an interactive terminal, ATBClone prompts whether to also delete the data directory:

atbclone remove WeChat2
Interactive prompt: Also delete data directory /Users/.../ATBClone/Data/WeChat2? [y/N]

Explicitly Remove Application and Data Directory (`--with-data`)

atbclone remove WeChat2 --with-data

Explicitly Remove Application Only and Keep Data (`--keep-data`)

atbclone remove WeChat2 --keep-data

Note: If the application or data directory is located in a root/admin path (e.g. /Applications), privilege escalation will be requested automatically once to clean up safely.

6. Recipe Management & Custom Extensions (`recipe`)

List All Built-in Recipes

atbclone recipe list

View Recipe Details for a Specific Bundle ID

atbclone recipe show com.tencent.xinWeChat

Custom & Override Recipes

Place a custom YAML recipe in ~/ATBClone/recipes/.yaml to automatically take precedence:

# Example: ~/ATBClone/recipes/com.example.customapp.yaml
bundle_id: com.example.customapp
app_name: CustomApp
strategy: hard_clone
app_type: cocoa # Options: cocoa, electron, chromium, firefox, generic
strip_sandbox: false # false (recommended): utilizes macOS native container isolation; true: strips App Sandbox
environment_injection:
  HOME: '{{ATB_DATA_DIR}}/Home'
  TMPDIR: '{{ATB_DATA_DIR}}/Tmp'
proxy:
  enabled: true
  type: http
  host: 127.0.0.1
  port: 7890

7. Deep Application Probing & Recipe Generation (`probe`)

Perform deep architecture and code signing inspection on any local .app bundle, analyze its engine (Chromium / Electron / Gecko / Native) and sandbox status, and output a recommended ATBClone Recipe YAML:

Basic Probing with Terminal Summary

atbclone probe /Applications/ATBCmder.app

Probe and Save Directly to Local Repository (`~/ATBClone/recipes/.yaml`)

atbclone probe /Applications/ATBCmder.app --save

Export Generated Recipe to a Specific Path

atbclone probe /Applications/ATBCmder.app -o /path/to/recipe.yaml

Output in Machine-Readable JSON

atbclone probe /Applications/ATBCmder.app --json

8. View Version & System Information (`version`)

# View detailed system and runtime environment information
atbclone version
Output version number only
atbclone version --short
or
atbclone --version

📋 Built-in Recipes

KakaoTalk validation: Concurrent launch with the original app and notifications have been checked. Clone login, separate-account data isolation, and login persistence after restarting the clone have not yet been verified.

🛠️ Prerequisites & Development Setup

Operating System: macOS 13.0+ (Apple Silicon arm64 / Intel x86_64)
Python: Python 3.12+ (strictly required for build_cli.sh compilation; Conda recommended)
System Tools: Xcode Command Line Tools installed (provides codesign, xcode-select, PlistBuddy)

# 1. Install Xcode Command Line Tools (if not already installed)
xcode-select --install
2. Activate Conda environment and install in development mode
conda activate ATBClone
pip install -e ".[dev,gui]"
3. Run environment self-check
atbclone doctor

🏷️ Semantic Version Management

The project adheres to semantic versioning x.y.z (current version: 1.1.1) and provides a dedicated version management script at scripts/manage_version.py:

# 1. Check version consistency across configuration files
python scripts/manage_version.py --show
2. Bump semantic version (patch: 1.1.1 -> 1.1.2, minor: 1.1.1 -> 1.2.0, major: 1.1.1 -> 2.0.0)
python scripts/manage_version.py --bump patch
python scripts/manage_version.py --bump minor
python scripts/manage_version.py --bump major
3. Set an explicit version
python scripts/manage_version.py 1.1.1
4. Preview changes without writing to disk
python scripts/manage_version.py --bump patch --dry-run

The script automatically updates version declarations in pyproject.toml, src/atbclone/__init__.py, and other configuration files.

🏗️ Standalone Binary Packaging (Build)

The project includes automated build scripts to package both the CLI and GUI into standalone binaries:

# 1. Build CLI standalone binary (dist/ATBCloneCli)
bash scripts/build_cli.sh
2. Build GUI DMG installer (dist/ATBClone-1.1.1.dmg)
bash scripts/build_gui.sh

The resulting standalone binary will be generated under dist/:

# Verify the built binary
./dist/ATBCloneCli --help
./dist/ATBCloneCli version
./dist/ATBCloneCli doctor
./dist/ATBCloneCli probe /Applications/ATBCmder.app

🧪 Running Tests

This project follows TDD and automated test verification practices, with full unit and integration test suites:

PYTHONPATH=src conda run -n ATBClone python -m pytest tests/ -v

📂 Directory & Storage Architecture

~/ATBClone/
├── config.yaml           # User configuration & preferences (language, tray, etc.)
├── clones.yaml           # Global clone state tracking registry
├── recipes/              # User custom recipe directory (optional overrides)
└── Data/                 # Isolated data directories per clone
    ├── WeChat2/
    │   ├── Home/         # Isolated user home directory
    │   └── Tmp/          # Isolated temporary directory
    └── Chrome2/          # Isolated Chrome User Data directory

src/atbclone/
├── cli/                  # CLI command layer (Click + Rich)
│   ├── cmd_clone.py      # Main clone command (supports auto-probing)
│   ├── cmd_doctor.py     # Environment checks
│   ├── cmd_list.py       # Clone listing
│   ├── cmd_probe.py      # Deep app architecture probing & recipe generation
│   ├── cmd_recipe.py     # Recipe management
│   ├── cmd_remove.py     # Clone removal
│   ├── cmd_update.py     # Clone update & sync
│   ├── cmd_version.py    # Version & system information
│   └── cmd_wizard.py     # Interactive wizard
├── core/                 # Core domain models & cloning engines
│   ├── app_inspector.py  # App metadata inspection & auto-numbering
│   ├── app_prober.py     # Deep probing, sandbox inspection & recipe extraction
│   ├── clone_task.py     # Clone task entity
│   ├── engines.py        # Soft & Hard cloning execution engines
│   ├── models.py         # Domain models
│   └── state.py          # YAML state management
├── gui/                  # Native macOS GUI desktop application layer (Toga / Briefcase)
│   ├── components/       # Reusable UI widgets (cards, sidebar, top bar)
│   ├── services/         # GUI service bridge (clone, doctor, probe, recipe, tray)
│   └── views/            # GUI views (dashboard, recipes, probe, doctor, settings, logs)
├── executor/             # Low-level executors (Subprocess / AppleScript elevation)
│   └── runner.py
└── recipes/              # Recipe models, loaders & 34 built-in rules
    ├── builtin/          # Built-in YAML recipes
    ├── loader.py         # Recipe matching & priority loader
    └── models.py         # Pydantic validation models

📖 User Manual & Documentation

For a comprehensive walkthrough of ATBClone GUI, custom recipes, engine mechanics, and troubleshooting, visit the online documentation at clone.aitobox.com:

🇺🇸 English User Guide (clone.aitobox.com/en/)

- Chapter 1: Basic Operations & Clone Management - Chapter 2: Custom Recipes for Niche Apps - Chapter 3: Under the Hood & Advanced Parameters - Chapter 4: FAQ & Diagnostic Troubleshooting

🇨🇳 简体中文用户使用手册 (clone.aitobox.com/zh/)

- 第一章：基础操作与分身管理 - 第二章：冷门应用规则定制与基础参数详解 - 第三章：实现原理解析与高级参数全解 - 第四章：常见问题 (FAQ)、系统体检与反馈

📄 License & Release Notes

Documentation: Online Docs | English Guide | 中文手册
License: GPL-3.0 License.
Release Notes: English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Deutsch | Français | Русский | Español

aitobox/ATBClone: The Ultimate macOS App Cloner & Sandbox Bypass Engine.

ATBClone (macOS Application Cloning Engine)

📥 Download

✨ Key Features

🖥️ Graphical User Interface (GUI — Recommended for General Users)

🚀 Command Line Interface (CLI — For Power Users & Scripting)

1. Interactive Wizard (CLI Guided Mode)

2. Command Line Quick Clone (clone)

Basic Clone (Auto-incremented name, defaults to ~/ATBClone/Apps)

Specify Clone Name and Output Directory

Custom Data Storage Directory (--data-dir)

Clone Applications without Pre-configured Recipes (Auto-triggers Prober)

Configure Dedicated Network Proxies (HTTP / SOCKS5)

Configure SOCKS5 proxy

Injection Strategy Selection (--injection-strategy)

Force dylib injection (guarantees native macOS system notifications and Menu Bar status icons)

Force Mach-O binary launcher hijack

3. List Cloned Applications (list)

4. Synchronize Clones After Primary App Updates (update)

5. Remove Clones (remove)

Interactive Removal (Recommended)

Interactive prompt: Also delete data directory /Users/.../ATBClone/Data/WeChat2? [y/N]

Explicitly Remove Application and Data Directory (--with-data)

Explicitly Remove Application Only and Keep Data (--keep-data)

6. Recipe Management & Custom Extensions (recipe)

List All Built-in Recipes

View Recipe Details for a Specific Bundle ID

Custom & Override Recipes

7. Deep Application Probing & Recipe Generation (probe)

Basic Probing with Terminal Summary

Probe and Save Directly to Local Repository (~/ATBClone/recipes/.yaml)

Export Generated Recipe to a Specific Path

Output in Machine-Readable JSON

8. View Version & System Information (version)

Output version number only

or

📋 Built-in Recipes

🛠️ Prerequisites & Development Setup

2. Activate Conda environment and install in development mode

3. Run environment self-check

🏷️ Semantic Version Management

2. Bump semantic version (patch: 1.1.1 -> 1.1.2, minor: 1.1.1 -> 1.2.0, major: 1.1.1 -> 2.0.0)

3. Set an explicit version

4. Preview changes without writing to disk

🏗️ Standalone Binary Packaging (Build)

2. Build GUI DMG installer (dist/ATBClone-1.1.1.dmg)

🧪 Running Tests

📂 Directory & Storage Architecture

📖 User Manual & Documentation

📄 License & Release Notes

Reading Mode

Related Stories

The result of the C++26 DIS ballot

Cognitive Mercantilism: AI panic resembles fears of early capitalism

US Wages Share of GDI at 75 Year Low

Behind the scenes at the NeXT Computer office

PaperPilot – Zero-Cloud, Pure-Rust PDF Engine with WASM and MCP