#!/bin/sh # Starts Claude Code with every subagent routed to a remote sandbox via the cloud_agent MCP tool. self=$0 while [ -h "$self" ]; do dir=$(cd "$(dirname "$self")" && pwd) self=$(readlink "$self") case $self in /*) ;; *) self=$dir/$self ;; esac done root=$(cd "$(dirname "$self")/.." && pwd -P) # -P: npm link adds a linked folder too # `cloudy-cloud help ` and `cloudy-cloud --help|-h` print that command's help. They never run it # or ask for setup. `--help` counts only as the last argument with no `--` before it (so `--task '--help'` is a task), # and `help -p` still goes to claude. For mcp, only `mcp`, `mcp add|ls|rm` are ours; `mcp list -h` is Claude Code's. case ${1:-} in help) if [ $# -gt 1 ]; then case $2 in -*) ;; *) shift; exec node "$root/src/cli-help.mjs" "$@" ;; esac; fi ;; setup|--setup|coordinator|shell|display|open|mcp|mcp-server|protect|doctor|dashboard|machines|branches) case $1:${2:-} in mcp:''|mcp:--help|mcp:-h|mcp:add|mcp:ls|mcp:rm) ;; mcp:*) n=-1 ;; esac [ "${n:-}" = -1 ] || n=0 [ "$n" = -1 ] || for a in "$@"; do n=$((n + 1)) case $a in --) break ;; --help|-h) if [ "$n" -eq $# ]; then if [ "$1" = --setup ]; then shift; set -- setup "$@"; fi exec node "$root/src/cli-help.mjs" "$@" fi ;; esac done ;; esac # `cloudy-cloud mcp-server` runs the MCP server on stdio (the transport the site's server card names). # It prints nothing itself and runs before the setup check: an empty config still answers tools/list. # Migration runs first: the server creates the new config directory, which would block it; the notice # goes to stderr because stdout is the MCP channel. if [ "${1:-}" = mcp-server ]; then shift . "$root/bin/migrate-config.sh"; migrate_config >&2 exec node "$root/src/server.mjs" "$@" fi # `cloudy-cloud dashboard [--demo]` opens a read-only local web page about your boxes. if [ "${1:-}" = dashboard ]; then shift exec node "$root/src/dashboard.mjs" "$@" fi # `cloudy-cloud open [--share|--unshare]` reaches an app running on a cloud machine. if [ "${1:-}" = open ]; then shift exec node "$root/src/open.mjs" "$@" fi # `cloudy-cloud shell [-- cmd...]` opens a shell on a cloud machine, or runs one command there. if [ "${1:-}" = shell ]; then shift exec node "$root/src/shell.mjs" "$@" fi # `cloudy-cloud display [--control] [--ttl S] [--screenshot FILE] [--unshare]` prints a link to a machine's desktop. if [ "${1:-}" = display ]; then shift exec node "$root/src/display.mjs" "$@" fi # `cloudy-cloud doctor` checks the self-hosted machine (the active provider only). if [ "${1:-}" = doctor ]; then shift exec node "$root/src/self-hosted-setup.mjs" doctor "$@" fi # `cloudy-cloud protect [owner/repo] [--yes]` creates a no-bypass ruleset on the default branch (asks first). if [ "${1:-}" = protect ]; then shift exec node "$root/src/protect.mjs" "$@" fi # `cloudy-cloud branches prune [--yes]` deletes empty or merged cloudy-cloud/* branches on origin (dry run by default). if [ "${1:-}" = branches ]; then shift exec node "$root/src/branches.mjs" "$@" fi # `cloudy-cloud machines [ls]` lists your Cloudy Cloud machines; `machines stop ` deletes them. if [ "${1:-}" = machines ]; then shift exec node "$root/src/machines.mjs" "$@" fi # update_notice: one line when a newer version is on npm. Interactive terminals only; no node starts when opted out. update_notice() { if [ -t 1 ] && [ -t 2 ] && [ -z "${CI:-}" ] && [ "${CLOUDY_CLOUD_NO_UPDATE_CHECK:-}" != 1 ]; then node "$root/src/update-check.mjs" || true; fi } # `cloudy-cloud pi|free-pi [args]` starts pi or free-pi as the main session with the cloud_agent tools. if [ "${1:-}" = pi ] || [ "${1:-}" = free-pi ]; then update_notice exec node "$root/src/host-pi.mjs" "$@" fi # `cloudy-cloud coordinator ...` manages cloud coordinators instead of starting Claude Code. if [ "${1:-}" = coordinator ]; then shift exec node "$root/src/coordinator.mjs" "$@" fi # `cloudy-cloud mcp add |ls|rm ` chooses which MCP servers cloud subagents get. # Claude Code's own `mcp list`, `mcp add -- ` and so on still go to claude below. if [ "${1:-}" = mcp ]; then case "$#:${2:-}" in 1:|2:ls|3:add|3:rm) shift; exec node "$root/src/mcp-cli.mjs" "$@" ;; 4:add) if [ "${4:-}" = --allow-literal ]; then shift; exec node "$root/src/mcp-cli.mjs" "$@"; fi ;; esac fi # `cloudy-cloud opencode [args]` starts opencode (instead of Claude Code) with the cloud_agent tools. A subcommand, because # `--agent` is already a Claude Code option that is passed through. if [ "${1:-}" = opencode ]; then shift . "$root/bin/migrate-config.sh"; migrate_config update_notice exec node "$root/src/host-opencode.mjs" "$@" fi # `cloudy-cloud setup` (or --setup) runs install.sh from this folder, whatever the current folder is. case ${1:-} in setup|--setup) shift; exec "$root/install.sh" "$@" ;; esac # `cloudy-cloud --version` prints the package version; `--help`, `-h` and `help` (alone) print Cloudy Cloud's own help. if [ $# -eq 1 ]; then case $1 in --version) sed -n 's/^ "version": *"\([^"]*\)".*/\1/p' "$root/package.json" where=$(cd "$root" && pwd -P); home=$(cd "${HOME:-/nonexistent}" 2>/dev/null && pwd -P) if [ -n "$home" ] && [ "$home" != / ]; then case $where in "$home") where="~" ;; "$home"/*) where="~${where#"$home"}" ;; esac; fi echo "installed at $where"; exit 0 ;; --help|-h|help) cat <<'EOF' Cloudy Cloud: give every subagent of your coding agent its own cloud machine. Usage: cloudy-cloud [command] [options] (no command) Start a Claude Code session codex [args] Start the Codex CLI with the cloud_agent tools opencode [args] Start opencode with the cloud_agent tools pi [args] Start pi as the main session (with cloud_agent) free-pi [args] Start free-pi as the main session (with cloud_agent) setup [--more] [--check-only] Check your tools and save your keys coordinator Manage always-on cloud coordinators shell [-- cmd] Open a shell on a cloud machine, or run one command display Print a link to a cloud machine's desktop open Reach an app running on a cloud machine mcp add|ls|rm Choose which MCP servers cloud subagents get mcp-server Run the MCP server on stdio (for other MCP clients) branches prune Delete empty or merged cloudy-cloud/* branches dashboard Open a read-only web page about your cloud machines machines List or delete your Cloudy Cloud machines protect [owner/repo] Block direct pushes to the default branch (asks first) doctor Check your own machine (self-hosted provider) --version Print the version More on one command: cloudy-cloud --help Any other arguments go to claude, for example: cloudy-cloud -p "" Docs: https://cloudycloud.tech/docs/ Claude Code's own options: claude --help EOF exit 0 ;; esac fi # Messages use the same look as src/ui.mjs: a terminal gets marks and attributes (TTY, TERM not dumb); # colour is on only without NO_COLOR and CLICOLOR=0. The basic 16 colours read on light and dark themes alike. say_init() { c_x=; c_acc=; c_dim=; c_warn=; c_err=; m_warn='!'; m_hint='>'; m_err='[x]'; a_next='->' if [ -t 2 ] && [ "${TERM:-dumb}" != dumb ]; then case "${LC_ALL:-${LC_CTYPE:-${LANG:-}}}" in *[Uu][Tt][Ff]-8*|*[Uu][Tt][Ff]8*) m_warn='▲'; m_hint='›'; m_err='✖'; a_next='→' ;; esac if [ -z "${NO_COLOR:-}" ] && [ "${CLICOLOR:-}" != 0 ]; then c_x=$(printf '\033[0m'); c_acc=$(printf '\033[1;34m'); c_dim=$(printf '\033[2m'); c_warn=$(printf '\033[33m'); c_err=$(printf '\033[31m') fi fi } say_init # One bare word on its own that is not a command (for example `cloudy-cloud ls`) is most likely a typo, not a prompt. # A prompt with spaces, any option, more than one argument and Claude Code's own subcommands keep working. if [ $# -eq 1 ]; then case $1 in -*|*[[:space:]]*|codex|mcp|agents|attach|auth|auto-mode|gateway|import|install|logs|plugin|plugins|purge|respawn|rm|sessions|setup-token|stop|kill|ultrareview|update|upgrade|config) ;; *) if [ -t 2 ] && [ "${TERM:-dumb}" != dumb ]; then printf ' %s%s%s cloudy-cloud: "%s" is not a command.\n' "$c_err" "$m_err" "$c_x" "$1" >&2 printf ' %s%s Next: cloudy-cloud --help%s\n' "$c_acc" "$a_next" "$c_x" >&2 case $1 in *[!A-Za-z0-9._/@:+=,-]*) ;; *) printf ' %s%s To send it to Claude as a prompt: cloudy-cloud -p "%s"%s\n' "$c_dim" "$m_hint" "$1" "$c_x" >&2 ;; esac else printf 'cloudy-cloud: "%s" is not a command. See: cloudy-cloud --help\n' "$1" >&2 # Suggest -p only when the word is safe to paste inside double quotes. case $1 in *[!A-Za-z0-9._/@:+=,-]*) ;; *) printf 'To send it to Claude as a prompt: cloudy-cloud -p "%s"\n' "$1" >&2 ;; esac fi exit 2 ;; esac fi # `cloudy-cloud codex [codex args]` starts the Codex CLI (instead of Claude Code) with the same cloud_agent tools. It is a subcommand # rather than --agent codex because claude already has its own --agent flag, which every other argument is passed to. agent=claude if [ "${1:-}" = codex ]; then agent=codex; shift; fi warn() { printf ' %s%s%s %s' "$c_warn" "$m_warn" "$c_x" "$1" >&2; [ -z "${2:-}" ] || printf ' %s%s%s' "$c_dim" "$2" "$c_x" >&2; printf '\n' >&2; } hint() { printf ' %s%s %s%s\n' "$c_dim" "$m_hint" "$1" "$c_x" >&2; } # Keys saved here reach only the MCP server, so the main session keeps its normal login. . "$root/bin/migrate-config.sh"; migrate_config config=${CLOUDY_CLOUD_CONFIG:-$HOME/.config/cloudy-cloud/env} # A coordinator holds the Instabox key as the proxy secret CLOUDY_CLOUD_INSTABOX_API_KEY (the INSTABOX_ prefix is reserved, # so the secret cannot carry that name). Its value here is a placeholder that Instabox swaps on its way to api.instabox.sh. if [ -z "${INSTABOX_API_KEY:-}" ] && [ -n "${CLOUDY_CLOUD_INSTABOX_API_KEY:-}" ]; then export INSTABOX_API_KEY="$CLOUDY_CLOUD_INSTABOX_API_KEY"; fi find_missing() { missing= # The provider comes from the environment or the saved file; Instabox is the default. provider=$(printenv CLOUDY_CLOUD_PROVIDER) [ -n "$provider" ] || provider=$(sed -n 's/^CLOUDY_CLOUD_PROVIDER=//p' "$config" 2>/dev/null | tail -n 1) if [ "$provider" = self-hosted ]; then # Inside a coordinator (local mode) the Docker socket stands in for the SSH host; elsewhere the SSH address counts. # Each counts from the environment or the file. selflocal=$(printenv CLOUDY_CLOUD_SELF_HOSTED_LOCAL) [ -n "$selflocal" ] || selflocal=$(sed -n 's/^CLOUDY_CLOUD_SELF_HOSTED_LOCAL=//p' "$config" 2>/dev/null | tail -n 1) if [ "$selflocal" = 1 ]; then sock=$(printenv CLOUDY_CLOUD_DOCKER_SOCKET) [ -n "$sock" ] || sock=$(sed -n 's/^CLOUDY_CLOUD_DOCKER_SOCKET=//p' "$config" 2>/dev/null | tail -n 1) # The configured path is the socket's place on the box; a coordinator sees it mounted at /var/run/docker.sock. if [ -z "$sock" ] || [ ! -e "${CLOUDY_CLOUD_DOCKER_SOCKET_IN:-/var/run/docker.sock}" ]; then missing='Docker socket (CLOUDY_CLOUD_DOCKER_SOCKET, and the socket mounted in this container)' fi elif [ -z "$(printenv CLOUDY_CLOUD_SSH_HOST)" ] && ! grep -q '^CLOUDY_CLOUD_SSH_HOST=.' "$config" 2>/dev/null; then missing='self-hosted machine (CLOUDY_CLOUD_SSH_HOST)' fi elif [ "$provider" = microsandbox ]; then # The msb binary: CLOUDY_CLOUD_MSB_BIN (environment or file), else the installer's default, else PATH — # the same ladder src/providers/microsandbox.mjs uses. msb=$(printenv CLOUDY_CLOUD_MSB_BIN) [ -n "$msb" ] || msb=$(sed -n 's/^CLOUDY_CLOUD_MSB_BIN=//p' "$config" 2>/dev/null | tail -n 1) if [ -z "$msb" ]; then if [ -x "$HOME/.local/bin/msb" ]; then msb=$HOME/.local/bin/msb else msb=$(command -v msb 2>/dev/null); fi fi [ -n "$msb" ] || missing='microsandbox CLI (msb)' # The Instabox key counts from the environment or the file. elif [ -z "$(printenv INSTABOX_API_KEY)" ] && ! grep -q '^INSTABOX_API_KEY=.' "$config" 2>/dev/null; then missing='Instabox API key' fi # Only the saved file counts for the subagent's Claude login: wrappers such as cmux's # `claude` can remove ANTHROPIC_API_KEY from the environment before Claude Code starts. # A Claude secret named in CLOUDY_CLOUD_PROXY_SECRETS (stored as an Instabox secret) counts too. # A Codex host needs no Claude login; a worker that does needs it is refused with its own next step. if [ -z "$missing" ] && [ "$agent" = claude ] && ! grep -qE '^(CLAUDE_CODE_OAUTH_TOKEN|ANTHROPIC_API_KEY)=.' "$config" 2>/dev/null \ && { [ "$provider" = self-hosted ] || ! sed -n 's/^CLOUDY_CLOUD_PROXY_SECRETS=//p' "$config" 2>/dev/null | tail -n 1 | tr -d ' \t' | grep -qE '(^|,)(CLAUDE_CODE_OAUTH_TOKEN|ANTHROPIC_API_KEY)(,|$)'; }; then missing='Claude token' fi } find_missing if [ -n "$missing" ]; then warn "cloudy-cloud is not set up yet" "no $missing in $config" hint "Run: cloudy-cloud setup" [ -t 0 ] || exit 1 printf ' %s?%s %sRun setup now?%s %s[Y/n]%s ' "$c_acc" "$c_x" "$c_acc" "$c_x" "$c_dim" "$c_x" >&2 IFS= read -r answer || answer=n case $answer in n*|N*) exit 1 ;; esac "$root/install.sh" || exit 1 find_missing [ -z "$missing" ] || { warn "cloudy-cloud: still no $missing" "run: cloudy-cloud setup"; exit 1; } fi if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then warn "This folder is not a git repository, so subagents can't start here." "run cloudy-cloud from inside a repo with a github.com origin" elif ! git remote get-url origin 2>/dev/null | grep -q 'github\.com'; then warn "This repo has no github.com origin, so subagents can't push their work." "add one: git remote add origin https://github.com/OWNER/REPO.git" fi case $root in *'"'*|*'\'*) warn "cloudy-cloud: install path contains a quote or backslash"; exit 1 ;; esac # Single quotes keep ${VAR:-} literal; Claude Code expands them, so secrets never appear in argv. # CLOUDY_CLOUD_CONFIG is included so the server reads the same file as this launcher. export CLOUDY_CLOUD_CONFIG="$config" update_notice if [ "$agent" = codex ]; then exec node "$root/src/host-codex.mjs" "$@"; fi envjson='{"CLOUDY_CLOUD_CONFIG":"${CLOUDY_CLOUD_CONFIG:-}","CLOUDY_CLOUD_PROVIDER":"${CLOUDY_CLOUD_PROVIDER:-}","INSTABOX_API_KEY":"${INSTABOX_API_KEY:-}","ANTHROPIC_API_KEY":"${ANTHROPIC_API_KEY:-}","CLAUDE_CODE_OAUTH_TOKEN":"${CLAUDE_CODE_OAUTH_TOKEN:-}","CLOUDY_CLOUD_PROFILES":"${CLOUDY_CLOUD_PROFILES:-}","CLOUDY_CLOUD_WORKER_HOURS":"${CLOUDY_CLOUD_WORKER_HOURS:-}","CLOUDY_CLOUD_STARTS_PER_MIN":"${CLOUDY_CLOUD_STARTS_PER_MIN:-}","CLOUDY_CLOUD_MAX_INSTABOX_CALLS":"${CLOUDY_CLOUD_MAX_INSTABOX_CALLS:-}","CLOUDY_CLOUD_PROXY_SECRETS":"${CLOUDY_CLOUD_PROXY_SECRETS:-}","CLOUDY_CLOUD_APT_PACKAGES":"${CLOUDY_CLOUD_APT_PACKAGES:-}"' # The egress allowlist reaches the server only when it is set, so a shell value survives modes that restrict # inherited MCP variables. A set-but-empty value expands to a space: still set, so the server rejects it instead # of silently dropping the policy; unset leaves the variable out entirely. envjson="${envjson%\}}" [ -z "${CLOUDY_CLOUD_EGRESS_ALLOW+x}" ] || envjson="$envjson"',"CLOUDY_CLOUD_EGRESS_ALLOW":"${CLOUDY_CLOUD_EGRESS_ALLOW:- }"' envjson="$envjson}" mcp="{\"mcpServers\":{\"cloud\":{\"command\":\"node\",\"args\":[\"$root/src/server.mjs\"],\"env\":$envjson}}}" settings='{"permissions":{"allow":["mcp__cloud__cloud_agent","mcp__cloud__cloud_agent_message","mcp__cloud__cloud_agent_wait","mcp__cloud__cloud_agent_result","mcp__cloud__cloud_agent_list","mcp__cloud__cloud_agent_stop"],"deny":["Agent","Workflow"]}}' prompt='Workers can run Claude Code, pi, oh-my-pi, Codex or opencode, on Claude or open models: for any other agent or model use the profile argument of cloud_agent (Claude Code on another model: glm, deepseek, particle, openrouter; pi: pi-glm, pi-deepseek, pi-particle; oh-my-pi: omp-glm, omp-deepseek, omp-particle; Codex: codex, codex-chatgpt, codex-openrouter; opencode: opencode-glm, opencode-deepseek, opencode-particle, opencode-openrouter), never the model argument. The openrouter, codex-openrouter and opencode-openrouter profiles also need model (the OpenRouter model id). The built-in Agent and Workflow tools are disabled. ALL delegation that would use a subagent must use the mcp__cloud__cloud_agent tool. Any instruction that mentions the Agent tool means mcp__cloud__cloud_agent. cloud_agent accepts profile to run a worker on another agent or model. Each cloud agent is a full agent (Claude Code by default) in a remote sandbox with the repo'"'"'s committed and tracked files (including uncommitted edits to tracked files), not local untracked files. Workflow: start every subagent with cloud_agent first; it returns at once and the agent works in the background. There are two modes, and the tool result tells you which one you are in. (1) Task mode: cloud_agent and cloud_agent_message return an MCP task. Each agent then shows in /tasks with live progress (tool uses, tokens, elapsed time, current step), and its result reaches you automatically when it finishes, with its agent_id. Do not call cloud_agent_wait for these; tell the user they can watch /tasks and stop an agent there. (2) Otherwise the call returns an agent_id and you call cloud_agent_wait with all the agent_ids to get results, and again after each cloud_agent_message. In both modes use cloud_agent_message for follow-ups, cloud_agent_list to check state and progress, and cloud_agent_stop when an agent is finished. Agents stay open until stopped or 60 idle minutes pass, so stop them when done. Starts are paced and queued automatically; a queued agent starts when a machine is free, so start as many as you need at once. Each agent pushes its work to origin branch cloudy-cloud/; nothing is copied into the local repo automatically. Get an agent'"'"'s work with git fetch origin cloudy-cloud/ (the result says when it was pushed). If an agent fails or disappears, whatever it pushed is still on origin cloudy-cloud/. When a cloud_agent tool returns an error, follow its Next step, and relay its Tell the user line to the user when present. cloud_agent also takes machine (linux by default; android, omarchy, gpu, macos). gpu and macos need consent in the env file, so relay the error Tell the user line and do not retry. To look at a worker, run cloudy-cloud shell -- or cloudy-cloud display ; a display link is a secret, never put it in a PR, issue or report.' # On a coordinator machine (set by `coordinator start`) the keys are placeholders that Instabox swaps for the real values. if [ -n "${CLOUDY_CLOUD_COORDINATOR:-}" ]; then prompt="$prompt This session is a cloud coordinator and its permission checks are off, so no prompt will appear; never wait for one. This machine holds placeholders for the Instabox key, the Claude token and the provider API keys, not the real keys; Instabox swaps a placeholder for the real key only in requests to that key's own host. Never print, share, commit or send a placeholder anywhere, never read ~/.config/cloudy-cloud/env into a message or a file, and never pass a placeholder to workers except through cloudy-cloud itself, which starts workers for you." if [ -n "${CLOUDY_CLOUD_DELETE_AT:-}" ]; then prompt="$prompt Your machine is deleted by the server at $CLOUDY_CLOUD_DELETE_AT; push your work well before then. When your work is done, do these steps in order: stop every worker with cloud_agent_stop, push your branches, write your report, then run ~/cloudy-cloud/bin/cloudy-cloud coordinator finish. It refuses while work is unpushed or workers are running, and otherwise deletes this machine. Do not run it until the report is pushed." fi fi # A parent cloudy-cloud running this as a nested coordinator passes extra rules here, so there is one prompt flag. if [ -n "${CLOUDY_CLOUD_EXTRA_PROMPT:-}" ]; then prompt="$prompt $CLOUDY_CLOUD_EXTRA_PROMPT" fi export MCP_TOOL_TIMEOUT="${MCP_TOOL_TIMEOUT:-1800000}" # Skills run "$CLOUDY_CLOUD_BIN" when `cloudy-cloud` is not on PATH (a source checkout). export CLOUDY_CLOUD_BIN="$root/bin/cloudy-cloud" # An unattended coordinator cannot answer "New MCP server found in this project"; only the servers above are used there. strict= [ -z "${CLOUDY_CLOUD_COORDINATOR:-}" ] || strict=--strict-mcp-config # Nobody can answer a permission prompt there (#88), so checks are off like for workers. The deny list in --settings still applies. bypass= [ -z "${CLOUDY_CLOUD_COORDINATOR:-}" ] || bypass=--dangerously-skip-permissions exec claude --mcp-config "$mcp" ${strict:+"$strict"} ${bypass:+"$bypass"} --settings "$settings" --append-system-prompt "$prompt" "$@"