SSH into a GitHub Codespace with gh codespace ssh

You will connect an installed GitHub Codespace to your local terminal over SSH, either by selecting it interactively or by naming it directly. Allow about ten minutes for a ready Codespace, and longer if its container needs an SSH server added. 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 make sure the command and the Codespace are available. This guide assumes you already have a Codespace whose container is running and whose image provides 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 does not include one, add the Dev Container feature to devcontainer.json and rebuild the Codespace:

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

Do not assume that a shell-accessible container also accepts 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 a selection of Codespaces:

$ gh cs ssh

Select the intended workspace. The full command is gh codespace ssh; gh cs ssh is the documented shorthand. The command then starts an SSH session, so a prompt from the remote container is the expected result. Leave that session with the remote shell's normal exit command:

$ exit
logout

This is an ordinary SSH connection. It does not stop, delete or rebuild the Codespace. The command itself 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 Codespace name and do not want an interactive choice:

$ gh codespace ssh --codespace YOUR_CODESPACE_NAME

Replace the placeholder with the value shown by gh codespace list. If several workspaces are available, filter the interactive selection by repository:

$ 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. --repo-owner narrows the owner separately. These options only filter which Codespace is selected; they do not clone a repository or change its permissions.

4. Understand the SSH key choice

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

1. An identity passed with -i after the -- separator.
2. The automatic key, if it already exists.
3. The first valid key pair found through the SSH configuration.
4. A newly created automatic key.

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 expected by OpenSSH, and inspect the path before using it:

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

A private key is security-sensitive. Never paste it into a ticket or commit it to the repository. If you selected the wrong identity, end the session and repeat the command with the intended -i path. Do not delete an old key until you know which other connections use it.

5. Add Codespaces to OpenSSH

For repeated use, generate the per-Codespace OpenSSH configuration into a separate file:

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

Review the generated file before including it. It contains connection details for your Codespaces, so treat it like 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 SSH remotes. The Match all line makes the following include apply to every SSH invocation. If your existing configuration has a more specific rule that should win, review the combined output from ssh -G rather than guessing.

The append command changes ~/.ssh/config. To undo exactly this setup, remove the two lines you added, then test the remaining configuration with ssh -G. Keep a backup before editing a valuable SSH configuration:

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

6. Choose a port only when required

The --server-port option accepts an integer and defaults to 0, which means the command picks an unused port. Leave the default in place unless the Codespace's SSH service is listening on a known alternative port:

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

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

7. Diagnose a failed connection

First confirm the name, repository filter and Codespace state:

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

--debug writes debug data to a file. If you need a predictable location, use --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 after reviewing it if it contains connection details:

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

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