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

中文版 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 | 中文使用手册 .

📥 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.

1. 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).

1. 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 │ 未开启 │ └──────────┴─────────┴━━━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━━━━━┘

1. 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

1. 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.

1. 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/<bundle_id>.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

1. 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/<bundle_id>.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

1. 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

Category Application Bundle Identifier Strategy App Type Strip Sandbox

Instant Messaging & Collaboration WeChat com.tencent.xinWeChat Hard Clone cocoa ✔

WeCom (企业微信) com.tencent.WeWorkMac Hard Clone chromium ✔

QQ com.tencent.qq Hard Clone electron ✔

Lark (飞书) com.electron.lark Hard Clone electron ✔

Telegram (Native Swift) ru.keepcoder.Telegram Hard Clone cocoa ✔

Telegram Desktop org.telegram.desktop Hard Clone generic ✔

LINE jp.naver.line.mac Hard Clone cocoa ✔

KakaoTalk com.kakao.KakaoTalkMac Hard Clone cocoa ✔

Slack com.tinyspeck.slackmacgap Hard Clone electron ✔

Discord com.hnc.Discord Hard Clone electron ✔

Skype com.skype.skype Hard Clone electron ✔

AI Clients Claude com.anthropic.claudefordesktop Hard Clone electron ✔

ChatGPT (Codex) com.openai.codex Hard Clone cocoa ✔

ChatGPT (Standard) com.openai.chat Hard Clone cocoa ✔

Gemini com.google.GeminiMacOS Hard Clone cocoa ✔

Antigravity com.google.antigravity Hard Clone electron ✔

Antigravity IDE com.google.antigravity-ide Hard Clone electron ✔

Browsers Google Chrome com.google.Chrome Hard Clone chromium —

Microsoft Edge com.microsoft.edgemac Hard Clone chromium —

Brave Browser com.brave.Browser Soft Clone chromium —

Firefox org.mozilla.firefox Soft Clone firefox —

Tor Browser org.torproject.torbrowser Soft Clone firefox —

Arc Browser company.thebrowser.Browser Hard Clone chromium —

Media & Entertainment Bilibili (哔哩哔哩) com.bilibili.bilibiliPC Hard Clone electron ✔

Douyin (抖音) com.bytedance.douyin.desktop Hard Clone electron ✔

Netease Music (网易云音乐) com.netease.163music Hard Clone chromium ✔

Steam com.valvesoftware.steam Hard Clone cocoa ✔

Productivity & Utilities WPS Office com.kingsoft.wpsoffice.mac Hard Clone cocoa ✔

VideoFusion (剪映专业版) com.lemon.lvpro Hard Clone chromium ✔

CapCut com.lemon.lvoverseas Hard Clone chromium ✔

Developer Tools Cursor com.todesktop.230313mzl4w4u92 Soft Clone electron —

VS Code com.microsoft.VSCode Soft Clone electron —

Android Studio com.google.android.studio Hard Clone generic ✔

Zed dev.zed.Zed Soft Clone generic —

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

— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。