Cloud CLI Proxy

One command. One cloud machine. All traffic through your exit IP.

Out-of-the-box isolated cloud hosts for Claude Code and dev teams. Pre-installed AI coding tools, full-tunnel egress through designated IPs, zero leaks.

中文 | Documentation

Go · React · PostgreSQL · Docker · sing-box

Features

One-command access — curl | bash to authenticate, create container, and SSH in. Zero user config
cloud-claude local CLI — alias claude=cloud-claude to run remote Claude Code from your terminal; local cwd is sshfs-mounted at the same path in the container; optional local exec for commands like git; supports Auto/Full/SSHFS-Only mount modes and oversized-file throttling
Claude Code ready — Pre-installed in every container. All API requests auto-routed through designated exit IP
Full-tunnel egress — sing-box tun + Linux netns full-tunnel, nftables default-deny, no DNS/WebRTC leaks
Multi-protocol — 6 proxy protocols (SOCKS5 / VMess / VLESS / Shadowsocks / Trojan / HTTP)
Per-user isolation — Dedicated Docker containers with KasmVNC remote desktop + Chromium browser
Admin dashboard — React SPA for users, hosts, egress IPs, events, and stats; supports host bind mounts
Auto expiration — Auto-stop containers and block login on expiry
Multi-arch CI/CD — GitHub Actions builds linux/amd64 + linux/arm64 images
Self-explanatory error codes — cloud-claude explain <CODE> for detailed description and remediation
tmux multi-client sessions — Multiple clients can attach the same tmux session; supports --new-session for isolation and --take-over to detach others
Network resilience — Built-in Reconnector auto-recovers within 30s on disconnect; buffered input survives reconnections
doctor five-domain checks — cloud-claude doctor [network|auth|ssh|mount|disk] with --fix for auto-repair

Deployment

Docker Compose

git clone https://github.com/ZaneL1u/cloud-cli-proxy.git
cd cloud-cli-proxy

bash deploy/scripts/setup-env.sh

# Recommended: prefer prebuilt images (latest)
docker compose pull
docker compose up -d

curl http://127.0.0.1:8080/healthz
# {"status":"ok"}

setup-env.sh interactively generates all passwords and secrets. Supports built-in Docker PostgreSQL (zero-config) or external database.

Admin dashboard at http://YOUR_HOST:3000, API at :8080.

Optional local source build (fallback when prebuilt images are unavailable):

docker compose -f docker-compose.yml -f docker-compose.build.yaml --profile build-only build --no-cache
docker compose -f docker-compose.yml -f docker-compose.build.yaml up -d --force-recreate

Environment Variables

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string (required)	—
`ADMIN_USERNAME`	Admin username	`admin`
`ADMIN_PASSWORD`	Admin password (required)	—
`ADMIN_JWT_SECRET`	JWT signing secret (required)	—
`ADMIN_PORT`	Admin dashboard port	`3000`
`SSH_PROXY_PORT`	SSH proxy port	`2222`
`LOG_FORMAT`	Log format `json` / `text`	`json`
`LOG_LEVEL`	Log level	`info`

Usage

Admin Setup

Log into the admin dashboard, then:

Add egress IPs — Multiple proxy protocols, with one-click connectivity test
Create users — Set username, password, expiration
Create hosts — Create container for user and bind egress IP
Share access info — Copy the curl command from host details; for cloud-claude users also share: gateway HTTPS URL, host Short ID, and user password

User Access

Users run the command provided by admin:

curl -sSf http://YOUR_HOST/entry/abc123 | bash
# Enter password → wait for boot → auto SSH into cloud host

cloud-claude (local CLI, recommended)

After the admin creates the host, binds an egress IP, and the container is ready, give the user three things:

Field	Meaning
Gateway URL	Public HTTPS base URL of the control plane, e.g. `https://gw.example.com` (same origin you use for the admin UI in the browser; usually not the `:3000` admin dev port)
Short ID	Host short ID from the host detail page. If the user configures a user short ID instead, they connect to that user’s primary host
Password	The user’s password from the admin dashboard

Install the CLI once, run init, then from any project directory run cloud-claude — the cwd is mounted at the same path in the container. By default git runs locally (tune with proxy_commands in ~/.cloud-claude/config.yaml).

Install cloud-claude

Homebrew (macOS / Linux, recommended):

brew tap ZaneL1u/tap
brew install cloud-claude

One-liner (any platform):

curl -fsSL https://raw.githubusercontent.com/ZaneL1u/cloud-cli-proxy/main/scripts/install.sh | bash

Or download the matching tar.gz from Releases, or build from source:

go build -ldflags "-s -w" -trimpath -o cloud-claude ./cmd/cloud-claude

First-time setup

cloud-claude init
# Prompts: gateway, Short ID, password → ~/.cloud-claude/config.yaml

Flags or environment variables:

cloud-claude init --gateway https://gw.example.com --short-id abc123 --password your-password

export CLOUD_CLAUDE_GATEWAY=https://gw.example.com
export CLOUD_CLAUDE_SHORT_ID=abc123
export CLOUD_CLAUDE_PASSWORD=your-password
cloud-claude init

Daily use

cd ~/your/project   # repo root you want Claude Code to see

alias claude=cloud-claude   # optional

cloud-claude
cloud-claude -p "refactor this function"

Session management: By default attaches the existing tmux session for the same account; disconnects do not lose the workspace:

cloud-claude                  # default: attach existing session (multi-client)
cloud-claude --new-session    # force a new isolated session
cloud-claude --take-over      # take over the primary session and detach others

cloud-claude sessions                  # list current tmux sessions
cloud-claude sessions --attach 0       # attach a specific session

Mount modes: Auto mode picks the best strategy; you can also specify manually:

cloud-claude --mount-mode=auto         # default: HotSync preferred, falls back to SSHFS
cloud-claude --mount-mode=full         # HotSync + SSHFS dual-track (full features)
cloud-claude --mount-mode=sshfs-only   # SSHFS only (compatibility first)

Self-checks and troubleshooting:

cloud-claude doctor                    # full five-domain check (network / auth / ssh / mount / disk)
cloud-claude doctor mount --fix        # mount-only check with auto-repair
cloud-claude explain MOUNT_SSHFS_DISCONNECTED   # query error code details and remediation
cloud-claude env check                 # verify remote timezone, locale, egress IP, FUSE, etc.

Environment variables:

CLOUD_CLAUDE_NO_PROMOTION=1 — disable cold-file read promotion (enabled by default on Linux; skipped on macOS)
Set proxy_commands in ~/.cloud-claude/config.yaml (list of command names to run on the host). Default is git only; use an empty list to disable.
hot_sync_max_file_mb — per-file throttling threshold (default 50MB); files larger than this fall back to the cold path.

cloud-claude does: gateway auth → wait for container → sshfs mount at the same path → start Claude Code remotely. Terminal size, signals, and exit codes are forwarded; network jitters auto-recover within 30s with buffered input surviving reconnections.

Claude Code (via SSH)

Claude Code is pre-installed. Just use it:

claude

All Claude API requests are automatically routed through the designated exit IP. No proxy configuration needed.

KasmVNC Remote Desktop

Containers include KasmVNC + Chromium. Access the browser desktop via the admin dashboard.

Architecture

                                                    ┌───────────────────────────────────┐
User ──curl──> Control Plane (:8080) ──Docker──>    │ User Container                    │
                    │                                │  SSH + Claude Code + VNC          │
               PostgreSQL                            │  sshfs ← same path as local cwd  │
                    │                                │  sing-box tun Tunnel              │
              Admin SPA (:3000)                      │       ↓                           │
                    │                                │  Designated Exit IP               │
              SSH Proxy (:2222)                      └───────────────────────────────────┘
                    ↑                                           ↑
                    │                                           │
User ──cloud-claude──> auth + SSH + sshfs ──────────────────────┘

Component	Description
Control Plane	Go API — auth, user management, task orchestration, SSH proxy
Host Agent	Privileged agent — Docker containers, network namespaces, tunnels
User Container	Ubuntu 24.04 — OpenSSH + Claude Code + sshfs + KasmVNC + Chromium
cloud-claude	Go CLI — transparent `claude`; sshfs same-path mount; supports Auto/Full/SSHFS-Only mount modes, tmux multi-client sessions, auto-reconnect, doctor five-domain checks, and error code explanations
PostgreSQL	Persists users, hosts, egress IPs, tasks, and events
Admin SPA	React 19 + TypeScript + Vite + Tailwind CSS

Development

make setup    # Install deps
make db       # Start PostgreSQL
make dev      # Backend + frontend hot reload
make test     # Run tests

See make help for all commands.

Release And Changelog

Pushing a v* tag triggers the Release workflow automatically and does three things:

Runs CI quality gates first (Go tests + admin web build)
Creates a GitHub Release
Publishes multi-arch images (semver + latest)
Generates monorepo-grouped release notes and writes them to CHANGELOG.md

The default changelog groups are path-based:

Backend (Go / API, cmd + internal)
Frontend (web/admin)
Runtime & Deployment (deploy, compose files, workflows)
Docs (docs + READMEs)

Manual release example:

make release VERSION=1.5.0

Documentation

Full docs on GitHub Pages:

Quick Start — Deploy and first use
Deployment — systemd native deployment
Configuration — Environment variables and egress proxy setup
Architecture — System design and project structure
API Reference — Full Admin API
FAQ & Recovery — Troubleshooting and disaster recovery

License

MIT

Navigation Menu

Uh oh!

Cloud CLI Proxy

Features

Deployment

Docker Compose

Environment Variables

Usage

Admin Setup

User Access

cloud-claude (local CLI, recommended)

Install cloud-claude

First-time setup

Daily use

Claude Code (via SSH)

KasmVNC Remote Desktop

Architecture

Development

Release And Changelog

Documentation

License

Uh oh!

FilesExpand file tree

README.en.md

Latest commit

History

README.en.md

File metadata and controls

Cloud CLI Proxy

Features

Deployment

Docker Compose

Environment Variables

Usage

Admin Setup

User Access

cloud-claude (local CLI, recommended)

Install cloud-claude

First-time setup

Daily use

Claude Code (via SSH)

KasmVNC Remote Desktop

Architecture

Development

Release And Changelog

Documentation

License