CloudCode ☁️💻

A self-hosted web interface for managing and monitoring local CLI-based AI coding agents — remotely, from any device.

CloudCode is not a coding agent. It is a remote control layer for agents you already have installed and authenticated on your machine. You bring the agent (Claude Code, Gemini CLI, etc.) — CloudCode lets you monitor and interact with it from anywhere.

Start an agent on your laptop, walk away, and check in from your phone or tablet. CloudCode keeps the session alive, renders the output cleanly, and lets you stay in the loop wherever you are.

---

Why CloudCode?

• Agent agnostic: Works with Claude Code, Gemini CLI, OpenAI Codex, GitHub Copilot CLI, or any CLI tool.
• Task launch: Start tasks instantly from your mobile dashboard without opening a full terminal. CloudCode defaults to your recent projects and drops you into the live session view.
• Transcript logs: Shows the full session output in a scrollable, timestamped transcript view.
• QR code pairing: Scan a QR code from your terminal to authenticate your phone. No passwords or SSH keys.
• Persistent sessions: Sessions run inside tmux. Your agent keeps working if your laptop sleeps or your connection drops. Reconnect and pick up where you left off.
• Resilient connection: A server-side heartbeat and client-side watchdog detect dead connections in under 20 seconds. The browser's network-change event triggers an immediate reconnect when you switch between Wi-Fi and cellular — no waiting for backoff timers to drain.
• Flexible networking: Works on local Wi-Fi, over Tailscale (private network), or via Cloudflare Tunnels (no port-forwarding needed).
• Git worktree isolation: Run agents in isolated git worktrees to keep your working directory clean.

---

Prerequisites

• Node.js (v22+): Download Node.js
• Go (v1.22+): Download Go or brew install go (macOS)
• tmux:
  • macOS: brew install tmux
  • Ubuntu/Debian: sudo apt install tmux
• git: Download Git

Optional (for remote access outside your local network)

• Tailscale — private, secure remote access: Install Tailscale
• cloudflared — public tunnel without a VPN: Install Cloudflare Tunnel

---

Networking Options

Same Wi-Fi network (simplest)

Your phone and laptop are on the same network. No extra setup needed.

cloudcode run gemini-cli --rc

Remote, without a VPN (--tunnel)

Cloudflare creates a temporary public URL. Your session is still protected by the pairing token.

cloudcode run gemini-cli --rc --tunnel

Remote, via Tailscale (most secure)

Both devices run Tailscale. CloudCode auto-detects it and uses your private *.ts.net address.

cloudcode run gemini-cli --rc

---

Installation

npm install -g @humans-of-ai/cloudcode

Verify the install and check your system for dependencies:

cloudcode init

---

Usage

Launch an agent with remote control

cloudcode run claude-code --rc

Starts the agent in a tmux session, attaches your terminal, and prints a QR code to pair your phone.

Start a persistent server dashboard

cloudcode start --rc

Runs CloudCode as a background server so you can launch agents later from your phone.

---

CLI Power-User Features

Beyond the dashboard, you can manage your sessions directly from the terminal:

• cloudcode status: List all active sessions, their agents, and uptime.
• cloudcode attach <id>: Directly attach to a session's native tmux environment.
• cloudcode logs <id>: Stream clean semantic transcripts (Markdown) of a session. Use -f to follow live.
• cloudcode summary <id>: Automatically spin up a local agent to read the transcript and summarize the session for you (great for PR descriptions!).
• cloudcode stop <id>: Gracefully stop an active agent session.
• cloudcode init: Verify your environment (Node, Go, tmux, git) and detect installed agents.

Share an existing session

cloudcode share

Grabs the current tmux session and generates a pairing QR code.

Use a Cloudflare tunnel

cloudcode run claude-code --rc --tunnel

Run a custom CLI tool

cloudcode run custom --command "npx some-ai-tool" --rc

Send vs create

Use the dashboard Send box when you want the fastest path:

• It uses your recent agent and workspace defaults.
• It creates a background session automatically.
• It opens the live terminal first.

Use Create when you want full control:

• Pick the exact agent profile.
• Choose the workspace or worktree deliberately.
• Set a title and startup prompt before launch.

---

Architecture

• Backend: Node.js + Fastify + SQLite (via Better-SQLite3)
• Frontend: React + Tailwind CSS + xterm.js + react-markdown
• PTY engine: Go-based sidecar that bridges Node.js to UNIX pseudo-terminals
• Session multiplexer: tmux

---

FAQ

Is CloudCode a coding agent? No. CloudCode does not write code, call AI APIs, or make decisions. It is a remote control interface — a layer that wraps and exposes CLI tools you already have running on your machine. The intelligence comes entirely from the agent you choose to run.

Do I need an API key or AI subscription to use CloudCode? Not for CloudCode itself. However, the coding agents you run through it (Claude Code, Gemini CLI, etc.) require their own authentication, API keys, and subscriptions. Set those up first, verify they work in your terminal, then use CloudCode to manage them remotely.

Which coding agents are supported? Any CLI tool. CloudCode has built-in profiles for Claude Code, Gemini CLI, and OpenAI Codex, but you can run any command-line program using the custom profile. If it runs in a terminal, CloudCode can manage it.

Does my code or terminal output get sent to CloudCode servers? No. CloudCode is entirely self-hosted — it runs on your own machine and your data never leaves your network (unless you explicitly use a Cloudflare tunnel for remote access, in which case traffic passes through Cloudflare's infrastructure).

Why does CloudCode require Go? CloudCode uses a small Go-based sidecar to interface with UNIX pseudo-terminals (PTYs). Node.js cannot do this reliably natively. The sidecar is compiled once during installation and runs transparently in the background.

What happens if my laptop goes to sleep while an agent is running? The agent keeps running. Sessions are managed by tmux, which is independent of CloudCode's web server. Your agent's process continues as long as the machine is powered on. When you reconnect, CloudCode picks the session back up.

What happens to my phone's connection when it sleeps or switches networks? CloudCode's connection layer is designed for exactly this. A server-side heartbeat ping detects that your phone's WebSocket is gone within 15 seconds rather than waiting for TCP's multi-minute timeout. On the client side, the browser's online event fires the moment a new network interface is ready (e.g. after a Wi-Fi→cellular switch), triggering an immediate reconnect without cycling through an exponential backoff queue. In practice, the terminal is back live within a few seconds of your phone waking up or changing networks.

Can I run multiple agents at the same time? Yes. Each session is an independent tmux window. You can run as many concurrent sessions as your machine can handle and manage them all from the dashboard.

---

License

MIT — see LICENSE.

---

Built by Alex Chao (@alexchaomander). Find me on my socials!

· Twitter/X · LinkedIn · YouTube · Substack