Skip to content

README.md

Latest commit

 

History

History
176 lines (134 loc) · 7.21 KB

README.md

File metadata and controls

176 lines (134 loc) · 7.21 KB
Raw

runcode

The RunCode cloud workspace CLI. Connect your local coding agents (Claude Code, Codex), editors (VS Code Remote, JetBrains), and tools (git, rsync, ssh) to a RunCode cloud development workspace over SSH — with short-lived, workspace-scoped keys and your ~/.ssh left untouched.

License: MIT Go Platforms

A single static binary, no runtime dependencies beyond an OpenSSH client. It mints a fresh throwaway SSH keypair on your machine, registers only the public key with the RunCode gateway for a short window, and pins the gateway host key — so there is no first-connect prompt and no man-in-the-middle window. Your private key never leaves your computer.

It is also built for agents: every command takes --json, returns a stable error code, and uses disciplined exit codes, so a coding agent can drive a workspace programmatically.

Install

Linux / macOS (script): downloads the right archive from GitHub Releases and verifies its sha256 against checksums.txt before installing.

curl -fsSL https://raw.githubusercontent.com/runcode-io/runcode-cli/master/install.sh | sh

Homebrew:

brew install runcode-io/tap/runcode

Windows: download runcode_windows_amd64.zip (or arm64) from the latest release, unzip, and put runcode.exe on your PATH. You also need the OpenSSH client (Settings → Apps → Optional features → OpenSSH Client).

From source (Go 1.25+):

go build -o runcode .      # produces ./runcode

Via the agent plugin: if you use the RunCode agent plugin for Claude Code or Codex, you don't install this directly — the plugin downloads and verifies a pinned release of this binary on first use.

Quickstart

runcode login                 # opens your browser once, saves a token locally
runcode list                  # your workspaces (running = SSH-connectable)
runcode connect my-workspace  # attach a workspace (--start boots a stopped one)
runcode exec -- pytest -q     # run a command on the attached workspace

A successful connect attaches one sticky workspace, so exec, put/get, context, and statusline all target it without naming it again — until you disconnect.

Commands

Authentication

Command Description
login Authenticate in the browser and save an API token
logout Remove the saved API token

Workspaces

Command Description
list List your workspaces
connect <ws> Mint a session and attach a workspace (--start boots a stopped one, --wait blocks until SSH answers)
start <ws> Power a workspace on without attaching (--no-wait returns early)
stop [ws] Power a workspace down (compute billing pauses; storage persists)
open <ws> Open the workspace browser IDE (or print its URL with --print)
create Create a new workspace
delete <ws> Delete a workspace (irreversible)
current Show the attached workspace
status List cached sessions
disconnect Detach the sticky workspace (does not power it off)

Run commands

Command Description
ssh <ws> [-- <cmd>] Open a shell on a workspace, or run one command with -- <cmd>
exec -- <cmd> Run a command on the attached workspace (no name needed; preferred for agents)
context [ws] Print a workspace digest (cwd, git state, project markers, tool versions)

Files & ports

Command Description
put <local> <remote> Upload a local file to the attached workspace
get <remote> [--out <local>] Download a file from the attached workspace
write <remote> [--file <local>] Write a file on the attached workspace from stdin or --file
port-forward <port> Forward a workspace port to localhost (--local, --to, --cancel)

Editor integration

Command Description
config-ssh Write a managed ~/.ssh/config block so your own editor / git reach workspaces as runcode.<name> (--remove to undo)
install-statusline Wire the workspace status line into your Claude Code settings
statusline Print a one-line status segment for the current session

Maintenance

Command Description
doctor Diagnose the local setup (OpenSSH client, token, API base, reachability)
install-path Add runcode to your shell PATH
clean [ws] Remove cached session material

Every command accepts --json for machine-readable output. Run runcode <command> --help for full flags.

How it works

Three steps run automatically each time you connect:

  1. A key is born on your machine. runcode generates a fresh, throwaway SSH keypair locally and sends only the public key to RunCode. The private key never leaves your computer.
  2. RunCode returns a short-lived pass. The backend registers the key with the gateway for a short window (about 30 minutes) and returns a connection bundle with a pinned host key — no first-connect prompt, no MITM window.
  3. Your tools connect through the gateway. ssh, git, rsync, VS Code Remote, and your local coding agent reach the workspace through the RunCode gateway using an isolated config. Your ~/.ssh is untouched and your personal keys are never offered.

config-ssh is the one opt-in exception: it writes a clearly delimited, reversible block to ~/.ssh/config (one host per workspace) so your own tools can reach a workspace as runcode.<name>. The short-lived key refreshes on every connect, so the entry never goes stale.

Configuration

  • Token. runcode login saves an API token to ${XDG_CONFIG_HOME:-~/.config}/runcode/token (mode 0600). You can also supply it for one invocation via the RUNCODE_TOKEN environment variable.
  • Endpoints. Defaults to the RunCode control plane at https://app.runcode.io and the web app at https://runcode.io.
  • Session material (per-workspace bundles, generated keys, known_hosts) lives under ${XDG_CONFIG_HOME:-~/.config}/runcode/ws/<id>/ and is cleared by runcode clean.

Security

  • Only the public key is sent; the server never sees, stores, or can use your private key.
  • The gateway host key arrives pinned in the bundle — no TOFU prompt, no MITM window.
  • Sessions are short-lived (~30 min, server-capped) and scoped to a single workspace.
  • The CLI uses its own ssh config, so your personal keys are never offered. config-ssh is the one opt-in, fully reversible exception.
  • The control plane is HTTPS-only; the CLI refuses a non-HTTPS endpoint, so the token never rides over cleartext and the bundle can't be downgraded.
  • You land as the same user you already have in the browser IDE, so no new privilege is created.

Development

go build ./...           # build
go test ./...            # tests

License

MIT © 2026 RunCode