⊞
Windows 10 / 11
Download the signed x64 EXE, run the setup, follow virtualization prompts and restart Windows if asked. Select a compatible guest OS in Cage.
Windows installer ↗A beginner-friendly guide to downloading the right installer, preparing a guest environment, configuring a proxy, and opening your first Claude Code project.
Download the signed x64 EXE, run the setup, follow virtualization prompts and restart Windows if asked. Select a compatible guest OS in Cage.
Windows installer ↗Download the DMG, open it, drag Cage into Applications and launch it from Applications. Requires macOS 14 or newer.
Mac installer ↗Download the x86_64 DEB. Your machine needs KVM and user permissions for local VMs. Install using the package manager:
sudo apt install ./Cage-0.1.7-linux-amd64.debInstall the developer-signed Android ARM64 APK, or build and sign the iOS 17+ companion locally using a Mac, Xcode, and an Apple developer signing identity.
Mobile connection guide ↗These steps describe the normal first-run workflow. Labels can vary between releases.
Open Cage and follow the on-screen prompts to create a local username and password. Keep the password somewhere safe.
Select an available macOS, Windows, or supported Linux guest, depending on your host. Choose where Cage will store the environment's persistent disk.
Follow the guided guest installation process. You may need an official OS image and appropriate license. Cage will download or prepare guest tools when supported.
Open network or proxy settings. Import a Clash/Mihomo YAML subscription, local YAML file, or configure a supported HTTP/SOCKS5 node. Select a node and choose Apply proxy.
Review the checks and exit region shown by Cage. If a critical check fails, fix your proxy instead of assuming internet access is enabled.
Start the guest environment. Choose Open project or use the default workspace, then create a terminal and enter claude.
Complete the developer's Claude login or account authorization flow in the Cage browser. Your Claude account is separate from the local Cage login.
A shared project folder is not a disposable copy. Changes, deletions and Git operations can affect the real host files you shared. Back up important work first.
Confirm your CPU and operating system meet the host requirements. On Windows, enable the required supported virtualization platform; on Linux, check KVM device availability and access. Restart when the installer requests it.
Confirm your subscription or node is valid, select the intended exit, and apply the proxy again. Cage deliberately does not switch to direct host internet access when the proxy is unavailable.
Check disk space, network availability, the detailed error message and official image source. Retry after addressing the failure. Avoid deleting existing guest disks.
Make sure the guest environment and proxy checks are working, then retry the authorization in the Cage browser. Refer to the current developer troubleshooting guide.
The developer intends to preserve personal data, accounts, and persistent virtual disks during supported upgrades. Save your files, stop work, quit Cage, and keep a backup before replacing the application.
Full troubleshooting documentation ↗References: Project repository · Release v0.1.7 · Developer documentation
Independent informational content, not affiliated with Anthropic or the project developers. Check upstream documentation for newer releases.
URL -
https://claudecage.com/user-documentation
Metadata - Title Claude Cage User Documentation
Meta_description - Claude Cage user documentation: first steps, virtual machines, networking, account management, phone connections, remote SSH and troubleshooting.
last_reviewed