Claude Cage: an isolated desktop for Claude Code
An open-source app that runs the terminal, browser, and Claude Code inside a guest — a VM on your computer, or a container on a server you own — and does not fall back to the host network when the proxy fails.
Cage separates the machine you type on from the environment Claude sees. You bring your own proxy. Guest traffic is forced through it; failed checks leave the guest offline instead of leaking onto the host route. You can schedule more than one Claude Code subscription, continue a session from a phone, or place the environment on your own Linux server. None of that is a promise against account limits.
What it is
One window holds a terminal for Claude Code, an editor, and Cage's own browser for login. The guest can be macOS, Windows, or Linux. Only folders you explicitly open are shared. Existing Claude logins, browser profiles, and SSH keys on the host are not imported.
You import a Clash or Mihomo YAML file, pick a node, and apply it. Public egress defaults to IPv4 TCP through that proxy, DNS included. If the evidence for a network check is missing, the guest stays offline. Timezone and language can follow the proxy IP. The project's own docs treat those checks as samples, not a security audit, and not proof that an account will be left alone.
Next to a supported-region VPS with Tailscale and Orca
The VPS guide rents a machine in a region Claude supports, joins it with Tailscale, and renders Orca's browser on that machine. The exit IP is the VPS itself.
Cage's usual shape is a guest on the computer in front of you. The exit is whichever proxy node you select. If that node is still somewhere Claude does not support, the region rule is unchanged. Cage can also deploy over SSH onto a Linux server you already have, as a rootless container without KVM. Tasks then stay on the server, but networking is still the proxy you configured inside Cage, not "the page was opened on the VPS NIC" the way the Orca setup works.
Use the VPS page when you want a box whose geography is the geography of the account. Use Cage when you want a desktop that keeps the host and the guest apart and can juggle subscriptions. Both are third-party tools.
Where it runs
- macOS 14 or newer on Apple Silicon. Intel Macs are unsupported.
- Windows 10 22H2 or Windows 11, x64. A Windows 11 guest also needs a Pro, Enterprise, or Education host with Hyper-V. Other supported Windows hosts can use a Debian or Ubuntu 22.04 guest. Windows on ARM is unsupported.
- Debian 12, Ubuntu 22.04, or Ubuntu 24.04, x86_64. Linux on ARM is unsupported. A local VM needs KVM. A cloud server without
/dev/kvmcannot follow the desktop VM path; use the cloud deploy instead.
The installer includes the workbench and the proxy core. You do not install Go, Node, Docker, or Clash first. Cage does not sell a system license, a proxy, or a Claude account.
Getting started
Download from the homepage or GitHub Releases and check SHA256SUMS. On macOS, drag Cage into Applications. On Linux, only if that release actually ships a deb:
sudo apt install ./Cage-<version>-linux-amd64.deb
The package name is claude-cage so it does not collide with another program named cage. The desktop command is cage-desktop. Do not start it with sudo. For a local VM:
test -r /dev/kvm && test -w /dev/kvm
sudo apt install qemu-system-x86 qemu-utils ovmf openssh-client iproute2 git
If the device exists but you cannot write it, join the kvm group and log in again. Git on the host must be 2.38 or newer before Cage will allow git safety on a shared project. Ubuntu 22.04's default git is often older.
- Import a Clash or Mihomo YAML subscription or a local file, select a node, apply it. The project does not sell nodes.
- Pick a guest OS, or "match this computer", and a disk location, then install or start. The default disk cap is about 24 GiB. Later launches reuse that environment.
- Open a folder, or use the default workspace. Run
claudein a Cage terminal and finish login in Cage's browser, not the host browser.
For another agent, the installed Cage CLI exposes agent capabilities. The protocol is whatever that build implements. AGENTS.md in the repo is for contributors. Users follow the agent guide.
More than one subscription
Three different logins: the Cage account that unlocks the workbench, Claude Code subscriptions scheduled under Settings, and a website or Claude Desktop login. The last two are not added to the scheduler automatically.
After the guest is up, run claude auth login in a Cage terminal and finish it in Cage's browser. Then "add to schedule" from Settings → Claude accounts. Another subscription is "sign in to a new account", with its own config directory. The same subscription is not scheduled twice.
Auto-assign happens when you open a new Claude terminal: balance by open terminals and known remaining quota, or walk the list in order. Turning a seat off only affects future terminals. Five-hour and seven-day quotas are read from the official Claude Code inside the guest. A missing reading is not a live balance.
Cross-account handoff of one session requires a shared "continue group". Ungrouped accounts do not take each other's history. The upstream docs say this runs the official Claude Code in the guest and does not extract subscription tokens to proxy model calls. Whether two real subscriptions will accept the handoff is something you still have to verify.
Your server, and a phone
Cloud mode is for when the laptop should not run a VM, or the job should outlive the laptop. In the SSH sidebar, enter host, port, user, and a key or agent, compare the host key, then deploy. The server side is a rootless container: no KVM, but it does need a systemd user session, cgroup v2, user namespaces, enough subordinate IDs, /dev/fuse, and /dev/net/tun. Linger is an admin step if the service must survive logout. Requirements live in deploy/cloud/README.md. Do not switch to a privileged container or hand the environment the Docker socket.
Closing the local window leaves the server job running. Stopping it is an explicit action in the remote workbench. Updating the desktop app does not update the server. Accounts and proxy settings on the server are not copied from the laptop.
Android 8 or newer, arm64, can install the APK from the download page. iPhone needs iOS 17 or newer and, today, a build you sign yourself in Xcode on a Mac. On the desktop, Settings → remote connection → phone generates a QR code that lasts about two minutes, or a one-time pairing code. The phone displays and approves; Claude Code, the exit, the timezone, and the language stay on the paired computer. If the desktop has switched into an SSH workbench, phone pairing still points at the computer's local Cage.
Tool calls ask the phone for allow-once or deny. A pairing code is an authorization. A self-hosted relay is optional and only forwards the connection.
Limits
- Third-party software, moving quickly. What a public build can do is what that build's notes say. Review it.
- Network checks do not guarantee an account will be spared, and they are not a virtualization audit. The upstream account guide says the official client may still recognize the environment.
- Edits inside a shared project, including git, hit the original files on the host. Keep backups.
- Projects in one Cage config share one guest, one toolchain, and one set of accounts. They are not separate VMs.
- Public UDP, IPv6, ICMP, and direct host or LAN routes are off by default. Tailscale inside Cage is a separate switch.
- If the proxy is down, there is no silent direct-connect fallback. That is intentional.