// local development

Connect over SSH

Point Codex, Claude Code, VS Code Remote, Cursor, JetBrains, or plain git at a RunCode workspace over SSH. Your own tools, running against a full cloud machine, with short-lived keys and your ~/.ssh left alone.

How it works

Three steps run automatically each time you connect. It is secure by construction, not by configuration.

01

A key is born on your machine

The CLI generates a fresh, throwaway SSH keypair on your machine and sends only the public key to RunCode. Your private key never leaves your computer. It is never uploaded, and never stored on the server.

02

RunCode returns a short-lived pass

The backend registers that key with the gateway for a short window (about 30 minutes) and hands back a connection bundle with a pinned host key. That means no first-connect prompt and no man-in-the-middle window.

03

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.

Get started

1. Prerequisites

You need the OpenSSH client (ssh + ssh-keygen) on your PATH. macOS and most Linux ship it. On Windows 10/11 enable Settings → Apps → Optional features → OpenSSH Client. The CLI is a static Go binary that downloads itself on first use; no other runtime is needed.

2. Install the RunCode SSH tool

Add the RunCode agent plugin to Codex or Claude Code (see the Agent plugin guide), or install the standalone runcode CLI. Then confirm your machine is ready:

verify your setup
runcode doctor

3. Log in & connect

Logging in opens your browser once, and the token is delivered straight to your own machine and saved locally. Then attach a workspace and start running commands on it.

terminal
runcode login                 # opens your browser, saves a token
runcode list                  # your workspaces (running = connectable)
runcode connect my-workspace  # attach a workspace
runcode exec -- pytest -q     # run a command on it

Workspace stopped? Let the CLI boot it and wait until it actually answers, no trip to the dashboard needed:

terminal
# boot a stopped box, then wait until SSH actually answers:
runcode connect my-workspace --start --wait

Use your own editor

One opt-in command writes a clearly delimited, backed-up, removable block to your ~/.ssh/config, one host per workspace, reachable as runcode.<name>. Open it in VS Code Remote-SSH, JetBrains Gateway, or clone with git. The short-lived key refreshes automatically on every connect, so the entry never goes stale.

terminal
runcode config-ssh            # write ~/.ssh/config host entries

# now your own tools reach the box as runcode.<name>:
ssh runcode.my-workspace
git clone runcode.my-workspace:/home/ubuntu/workspace/app.git
code --remote ssh-remote+runcode.my-workspace /home/ubuntu/workspace

runcode config-ssh --remove   # take the entries back out

Moving files and previewing a dev server work the same way:

terminal
runcode put ./local.py src/app.py    # upload a file
runcode get logs/app.log --out .     # download a file
runcode port-forward 5173           # expose the workspace dev server locally

Built to be safe

  • Private key never leaves your machine

    Only the public key is sent. The server never sees, stores, or can use your private key.

  • Pinned host key, no TOFU prompt

    The gateway host key arrives in the bundle, so there is no first-connect prompt and no man-in-the-middle window.

  • Short-lived & workspace-scoped

    Sessions expire in around 30 minutes (server-capped) and grant access to one workspace, nothing else.

  • Isolated config, ~/.ssh untouched

    The CLI uses its own ssh config, so your personal keys are never offered. config-ssh is the one opt-in, fully reversible exception.

  • HTTPS-only control plane

    The CLI refuses a non-HTTPS endpoint, so your token never rides over cleartext and the bundle can’t be downgraded.

  • Same access as the web IDE

    You land as the same user you already have in the browser IDE, so no new privilege is created.

Command cheat sheet

runcode login Authorize this machine in the browser and save an API token
runcode list List your workspaces (running ones are SSH-connectable)
runcode connect <ws> Attach a workspace; --start boots a stopped one, --wait blocks until SSH answers
runcode start <ws> Boot a stopped workspace without attaching (--no-wait returns immediately)
runcode ssh <ws> [-- cmd] Open an interactive shell (bare) or run one command (with --) on a workspace
runcode exec -- <cmd> Run a command on the attached workspace (no name needed; preferred for agents)
runcode open <ws> Open the workspace browser IDE in your default browser
runcode config-ssh Write ~/.ssh/config entries so your own editor / git reach workspaces
runcode put / get Upload or download a file, byte-for-byte
runcode port-forward <port> Expose a workspace port locally (e.g. a dev server)
runcode stop Power a workspace down (pauses compute billing; storage persists)
runcode disconnect Detach, and work goes back to your local machine
runcode doctor Preflight: OpenSSH client, token, reachability

Looking for every command and flag? See the CLI reference.

Don’t have a workspace yet? Start one. It opens in your browser in seconds, then you can connect to it from here.