Skip to content
This repository has been archived by the owner on Oct 20, 2023. It is now read-only.

Latest commit

 

History

History
133 lines (88 loc) · 7.76 KB

README.md

File metadata and controls

133 lines (88 loc) · 7.76 KB
Raw

Codespaces Network Bridge

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

image

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 #9 and SSH setup doc for some of the known solutions.

The command will first open a Codespace selection dialog:

image

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

image

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

Useful links