Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/github/gh-net

A network bridge between a Codespace and a local machine.
https://github.com/github/gh-net

cli codespaces gh-extension network

Last synced: 4 months ago
JSON representation

A network bridge between a Codespace and a local machine.

Host: GitHub
URL: https://github.com/github/gh-net
Owner: github
Archived: true
Created: 2022-03-16T00:17:23.000Z (almost 3 years ago)
Default Branch: main
Last Pushed: 2022-09-15T21:35:01.000Z (over 2 years ago)
Last Synced: 2024-09-25T21:08:35.102Z (4 months ago)
Topics: cli, codespaces, gh-extension, network
Homepage: https://github.com/github/gh-net
Size: 86.9 KB
Stars: 285
Watchers: 11
Forks: 21
Open Issues: 32
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md

Awesome Lists containing this project

awesome-list - gh-net - A network bridge between a Codespace and a local machine. (Github tools)
awesome-gh-cli-extensions - **net** - Network bridge for [GitHub Codespaces](https://github.com/features/codespaces). (Github)

README

        ## Codespaces Network Bridge

🧪 *The extension is currently in the Preview stage, so some hiccups are expected. Please help us to improve [by submitting feedback](https://github.com/github/gh-net#troubleshooting)!*



This [GitHub CLI](https://cli.github.com/) 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](https://cli.github.com/).

## Prerequisites

1. This extension requires [GitHub CLI](https://cli.github.com/) version `v2.8.0` and up. Please make sure [to upgrade it](https://github.com/cli/cli#installation).

2. **If using GitHub CLI < [2.13.0](https://github.com/cli/cli/releases/tag/v2.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](https://github.com/cli/cli/releases/tag/v2.13.0) the `SSH` config is created automatically for all your Codespaces, otherwise follow [SSH setup](./docs/SSH_SETUP.md) instructions.

3. If your Codespace uses a non-default image, ensure that both the [GitHub CLI](https://cli.github.com/), `openssh-server`, and `sudo` are installed inside the codespace. Some distros need an `ssh` group too. Please see [linux dependencies doc](./docs/LINUX_DEPENDENCIES.md) for per-distro instructions.

## Installation

```shell

gh extension install github/gh-net

```

## Usage

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

```shell

gh net

```

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

Connection issues? Please see https://github.com/github/gh-net/issues/9 and [SSH setup doc](./docs/SSH_SETUP.md) 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](./docs/SUPPORTED_NETWORK_PROTOCOLS.md).

## Troubleshooting

- Something is missing? Please create a [✨ feature request](https://github.com/github/gh-net/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=).

- Something is incorrect? Please create a [🐛 bug report](https://github.com/github/gh-net/issues/new?assignees=&labels=bug&template=bug_report.md&title=).

- For known issues, refer to [👉 this list](https://github.com/github/gh-net/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue).

## Useful links

- [How it works](./docs/HOW_IT_WORKS.md)

- [About GitHub CLI](https://cli.github.com/)

- [About GitHub Codespaces](https://github.com/features/codespaces)

- [🔒 Source code](https://github.com/github/codespaces-vpn-gateway)