Claude guide CCBaga

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.

New · 12 November 2026 · about 4.6k GitHub stars when this page was written · MIT

Credit. Claude Cage is maintained by Lee-xeo. Repository: github.com/Lee-xeo/Claude-Cage. The project page lee-xeo.github.io/Claude-Cage currently redirects to claude-cage.com. Docs: claude-cage.com/docs. The project license is MIT. The bundled Mihomo binary is GPL-3.0. Cage is a fork of agent-vm and is not affiliated with Anthropic. Read the tree and the release notes yourself before you install it.
Short answer

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

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.

  1. Import a Clash or Mihomo YAML subscription or a local file, select a node, apply it. The project does not sell nodes.
  2. 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.
  3. Open a folder, or use the default workspace. Run claude in 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