gh-net

gh-net copied to clipboard

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 depends on the latest features of GitHub CLI(>= v2.8.0). Please make sure to upgrade it.

2. 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

Mac OSx:

gh extension install github/gh-net

Linux:

sudo gh extension install github/gh-net

The sudo permissions are required during extension installation on Linux due to https://github.com/cli/cli/issues/5456. Hopefully, it won't be the case in the future.

Usage

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

sudo gh net start

Connection issues? Please see https://github.com/github/gh-net/issues/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

• --codespace(-c): Codespace name to connect to. [codespace name] [default: none]
• --dns(-d): Enable/disable DNS resolution. [true | false] [default: true]
• --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]
• --telemetry: Enable/disable sending diagnostics telemetry (no PII data is sent). [true | false] [default: true]

Run gh net start -h for details.

Supported platforms

Mac OSx

Linux

Windows

Supported architectures

Mac OSx

Linux

Windows

Tested VPN Clients

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