SSH into a Codespace with gh codespace ssh

gh codespace ssh connects your local terminal to a running GitHub Codespace over SSH, either by picking one interactively or by naming it directly. Allow about ten minutes for a Codespace that is already ready, longer if its container needs an SSH server added first.

This guide describes GitHub CLI 2.87.3, installed on the machine used for these examples.

1. Check the local prerequisites

Install and authenticate GitHub CLI, then confirm both the command and the Codespace are available. This assumes a Codespace whose container is already running and whose image includes an SSH server:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh codespace list
$ gh codespace ssh --help

The SSH server is a Codespace prerequisite, not something gh codespace ssh installs for you. If the container image lacks one, add the Dev Container feature to devcontainer.json and rebuild the Codespace:

"features": {
  "ghcr.io/devcontainers/features/sshd:1": {
    "version": "latest"
  }
}

A shell-accessible container does not automatically accept SSH connections. Check the image or its Dev Container configuration first.

2. Connect interactively

Run the short form when you want GitHub CLI to show you a list of Codespaces to pick from:

$ gh cs ssh

Select the workspace you want. The full command is gh codespace ssh; gh cs ssh is the documented shorthand. It starts an SSH session, so a prompt from the remote container is exactly what you should see. Leave it the ordinary way:

$ exit
logout

This is an ordinary SSH connection: it does not stop, delete or rebuild the Codespace. The command needs no sudo, and adding elevated privileges locally will not repair a missing server inside the container.

3. Name or filter the Codespace

Use --codespace when you have a stable name and want to skip the interactive picker:

$ gh codespace ssh --codespace YOUR_CODESPACE_NAME

Swap in the value from gh codespace list. With several workspaces available, filter the interactive selection by repository instead:

$ gh codespace ssh --repo YOUR_GITHUB_USER/YOUR_REPOSITORY
$ gh codespace ssh --repo-owner YOUR_GITHUB_USER

--repo takes a repository in owner/name form, and --repo-owner narrows the owner on its own. Both only filter which Codespace gets selected; neither clones a repository or changes its permissions.

4. Understand the SSH key choice

On a first connection, the command can create a public and private key pair in ~/.ssh if it finds no valid existing pair. The selection order is easy to miss:

1. An explicit identity. Passed with -i after the -- separator.
2. The automatic key. If one already exists.
3. The first valid key pair. Found through your normal SSH configuration.
4. A newly created automatic key. As a last resort.

Pass SSH flags after -- so GitHub CLI does not mistake them for its own options:

$ gh codespace ssh --codespace YOUR_CODESPACE_NAME -- -i ~/.ssh/YOUR_KEY

Protect private keys with the permissions OpenSSH expects, and inspect the path before you trust it:

$ ls -l ~/.ssh/YOUR_KEY ~/.ssh/YOUR_KEY.pub
$ ssh-keygen -lf ~/.ssh/YOUR_KEY.pub

5. Add Codespaces to OpenSSH

For repeated use, generate a per-Codespace OpenSSH configuration into its own file:

$ mkdir -p ~/.ssh
$ gh codespace ssh --config > ~/.ssh/codespaces

Review the generated file before you include it anywhere; it holds connection details for your Codespaces, so treat it like any other SSH configuration:

$ sed -n '1,120p' ~/.ssh/codespaces
$ touch ~/.ssh/config
$ printf 'Match all\nInclude ~/.ssh/codespaces\n' >> ~/.ssh/config
$ ssh -G YOUR_CODESPACE_HOST > /tmp/codespace-ssh-settings
$ grep -E '^(hostname|user|port|identityfile) ' /tmp/codespace-ssh-settings

The generated configuration lets OpenSSH-aware tools use Codespace host names, including ssh, scp, rsync, sshfs and Git's own SSH remotes. Match all makes the include apply to every SSH invocation, so if your existing configuration has a more specific rule that should win, check the combined output of ssh -G rather than guessing.

The append command changes ~/.ssh/config. To undo exactly this setup, remove the two lines you added and retest with ssh -G. Keep a backup first, since a valuable SSH configuration is not something to edit blind:

$ cp --preserve=mode,timestamps ~/.ssh/config ~/.ssh/config.before-codespaces

6. Choose a port only when required

--server-port accepts an integer and defaults to 0, meaning the command picks an unused port itself. Leave that alone unless the Codespace's SSH service listens on a known alternative:

$ gh codespace ssh --codespace YOUR_CODESPACE_NAME --server-port 2222

A port value does not install or reconfigure the server. If the service actually listens on port 22, an arbitrary alternative will simply fail. Check the container's SSH configuration and logs through your normal Codespaces workflow before changing this option.

7. Diagnose a failed connection

Confirm the name, repository filter and Codespace state first:

$ gh codespace list
$ gh codespace ssh --codespace YOUR_CODESPACE_NAME --debug

--debug writes debug data to a file. For a predictable location, add --debug-file:

$ gh codespace ssh --codespace YOUR_CODESPACE_NAME --debug --debug-file /tmp/gh-codespace-ssh.log
$ sed -n '1,160p' /tmp/gh-codespace-ssh.log

Remove the temporary log once you have reviewed it, if it holds connection details:

$ rm -- /tmp/gh-codespace-ssh.log

Authentication failure means checking the selected identity and the public key's fingerprint. A refused connection means checking that an SSH server is installed and running in the container. If the command keeps picking the wrong workspace, use --codespace instead of guessing from the menu again. A successful handshake followed by an immediate disconnect usually points at the remote server or container configuration, not the local key-selection prompt.