Codespaces Network Bridge

🧪 The extension is currently in the Preview stage, so some hiccups are expected. Please help us to improve by submitting feedback!

This GitHub CLI extension allows you to bridge the network between a Codespace and your local machine, so the Codespace can reach out to any remote resource that is reachable from your machine. In other words, it uses your local machine as a network gateway to get to those resources.

For instance, if you are using a VPN client to connect to private enterprise network to access a database or any other remote resources, this extension enables you to use those private resources from within a Codespace.

About GitHub CLI.

Prerequisites

1. This extension requires GitHub CLI version v2.8.0 and up. Please make sure to upgrade it.

2. If using GitHub CLI < 2.13.0 only. The extension relies on gh codespace ssh command to establish SSH tunnel to a Codespace. If you use GitHub CLI >=2.13.0 the SSH config is created automatically for all your Codespaces, otherwise follow SSH setup instructions.

3. If your Codespace uses a non-default image, ensure that both the GitHub CLI, openssh-server, and sudo are installed inside the codespace. Some distros need an ssh group too. Please see linux dependencies doc for per-distro instructions.

Installation

gh extension install github/gh-net

Usage

To start network forwarding from a Codespace to a local machine, run:

gh net

Note: on Windows, you need to use a command prompt launched with Administrator privileges.

Connection issues? Please see github#9 and SSH setup doc for some of the known solutions.

The command will first open a Codespace selection dialog:

Select a codespace and press enter. The extension will connect to selected codespace and start forwarding network traffic:

There are two panels in the connected view of the extension:

• Panel on the left (NAT) shows the network address translation table for currently opened connections. For stateful protocols(e.g. TCP) the records are cleaned up automatically after a connection is closed, so the records will come and go as connections are established and teardown. For stateless protocols (e.g. UDP or ICMP) or unsuccessful TCP connections, the records are cleaned up after a delay; hence those may show up in the list for some time.
• Panel on the right (DNS) shows the resolved DNS records, as hostname, record, and time-to-live (TTL) values.

Press q or ctrl + c to stop the extension.

CLI Options

• --gui(-g): Enable/disable GUI mode. [true | false] [default: true]
• --trace(-t): Specify tracing verbosity. [none | trace | debug | info | warn | error] [default: info]
• --trace-dest: Specify tracing destination file. [file name] [default: none]
• --dns(-d): Enable/disable DNS resolution. [true | false] [default: true]
• --codespace(-c): Codespace name to connect to. [codespace name] [default: none]
• --telemetry: Enable/disable sending diagnostics telemetry (no PII data is sent). [true | false] [default: true]

Run gh net -h for details.

Supported platforms

Mac OSx

OS	Intel chip	Apple chip
Big Sur (v11)	✅	✅ *
Monterey (v12)	✅	✅ *

Windows

Architecture	AMD64
Windows 10	✅
Windows 11	✅

Linux

Distro	Local	Inside Codespace
Ubuntu	✅	✅
Debian	✅	✅
Fedora	✅	✅
Red Hat	✅	✅
Mint	✅	✅
OpenSUSE	✅	✅
Centos	✅	✅
Kali	✅	✅
Arch	✅	✅
Alpine	✅	✅ *

Supported Linux architectures

Architecture	Status
AMD64	✅
ARM64	✅
ARMv6	✅
ARMv7	✅

Tested VPN Clients

Name	Status
Viscocity	✅
GlobalProtect	✅
NordVPN	✅
Tailscale	✅

Legend: ✅ - supported 🏃 - in progress ? - unknown / not tested

For list of supported network protocols refer to this doc.

Troubleshooting

• Something is missing? Please create a ✨ feature request.
• Something is incorrect? Please create a 🐛 bug report.
• For known issues, refer to 👉 this list.

Useful links

• How it works
• About GitHub CLI
• About GitHub Codespaces
• 🔒 Source code