🧪 The extension is currently in Preview stage, so some hiccups are expected. Please help us to improve by submitting feedback!
This GitHub CLI extension allows to bridge 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 another 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.
-
This extension depends on the latest features of GitHub CLI(>= v2.8.0), please make sure to upgrade it. If run the
gh codespace selectcommand opens the codespace selection dialog, you are good to go. -
The extension relies on
gh codespace sshcommand to establish SSH tunnel to a Codespace, hence you need to setup ssh keys if you didn't before. If you can dosudo gh codespace ssh(sudois important since kernel might use different identity under non-root user) and connect to a Codespace successfully, - you are good to go. Refer to Generating a new SSH key and adding it to the ssh-agent for more info. List of known issues and workarounds for them can be found here. -
If your codespace uses a non-default image, ensure that both the GitHub CLI,
openssh-serverandsudoare installed inside the codespace. Some distros need ansshgroup too. Please see linux dependencies doc for per-distro instructions.
Mac OSx:
gh extension install github/gh-netLinux:
sudo gh extension install github/gh-netThe sudo is required during extension installation on Linux due to cli/cli#5456. Hopefully it won't be the case in the future.
To start network forwarding from a Codespace to a local machine, run:
sudo gh net startConnection issues? Please see github#9 for some common solutions.
This will provide 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 connection is closed so the records will come and go as connection is established and closed. For stateless protocols (e.g.UDPorICMP) or unsuccessfulTCPconnections the records are cleaned up after some time, so those will show up in the list for some time. - Panel on the right (
DNS) shows the resolvedDNSrecords, ashostname,recordandtime-to-live(TTL) values.
Press q or ctrl + c to stop the extension.
--gui: Enable/disable GUI mode. [true|false] [default:true]--dns: Enable/disable DNS resolution. [true|false] [default:true]--trace: Specify tracing verbosity. [none|trace|debug|info|warn|error] [default:info]--telemetry: Enable/disable sending diagnostics telemetry (noPIIdata is sent). [true|false] [default:true]
Run gh net start -h for details.
| OS | Local |
|---|---|
| Big Sur (v11) | ✅ |
| Monterey (v12) | ✅ |
| Distro | Local | Inside Codespace |
|---|---|---|
| Ubuntu | ✅ | ✅ |
| Debian | ✅ | ✅ |
| Fedora | ✅ | ✅ |
| Red Hat | ✅ | ✅ |
| Mint | ✅ | ✅ |
| OpenSUSE | ✅ | ✅ |
| Centos | ✅ | ✅ |
| Kali | ✅ | ✅ |
| Arch | ✅ | ✅ |
| Alpine | ✅ | ✅ * |
| Version | Local |
|---|---|
| Windows 10 | 🏃 |
| Windows 11 | 🏃 |
| Architecture | Status |
|---|---|
| Intel(AMD64) | ✅ |
| Apple silicon (ARM64) | ✅ * |
| Architecture | Status |
|---|---|
| AMD64 | ✅ |
| ARM64 | ✅ |
| ARMv6 | ✅ |
| ARMv7 | ✅ |
| Architecture | Status |
|---|---|
| AMD64 | 🏃 |
| i386 | 🏃 |
| Name | Status |
|---|---|
| Viscocity | ✅ |
| GlobalProtect | ✅ |
| NordVPN | ✅ |
| Tailscale | ✅ |
Legend: ✅ - supported 🏃 - in progress ? - unknown / not tested
For list of supported network protocols refer to this doc.
- Something is missing? Please create a ✨ feature request.
- Something is incorrect? Please create a 🐛 bug report.
- For list of known issues refer to 👉 this list.