Skip to main content
 

 

Forwarding ports in your codespace

In this article

You can forward ports in your codespace to test and debug your application. You can also manage the port protocol and share the port within your organization or publicly.

Note: Using GitHub Codespaces with JetBrains IDEs is currently in public beta and is subject to change.

About forwarded ports

Port forwarding gives you access to TCP ports running within your codespace. For example, if you're running a web application on a particular port in your codespace, you can forward that port. This allows you to access the application from the browser on your local machine for testing and debugging.

When an application running inside a codespace prints output to the terminal that contains a localhost URL, such as http://localhost:PORT or http://127.0.0.1:PORT, the port is automatically forwarded. If you're using GitHub Codespaces in the browser or in Visual Studio Code, the URL string in the terminal is converted into a link that you can click to view the web page on your local machine. By default, GitHub Codespaces forwards ports using HTTP.

Automatic port forwarding

You can also forward a port manually, label forwarded ports, share forwarded ports with members of your organization, share forwarded ports publicly, and add forwarded ports to the codespace configuration.

Note: Organization owners can restrict the ability to make forward ports available publicly or within the organization. For more information, see "Restricting the visibility of forwarded ports."

Forwarding a port

You can manually forward a port that wasn't forwarded automatically.

  1. In your codespace, under the text editor, click "Ports". Ports tab

  2. Under the list of ports, click Add port.

    Add port button

  3. Type the port number or address, then press enter.

    Text box to type port button

Using HTTPS forwarding

By default, GitHub Codespaces forwards ports using HTTP but you can update any port to use HTTPS, as needed. If you update a port with public visibility to use HTTPS, the port's visibility will automatically change to private.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Right click the port you want to update, then hover over Change Port Protocol. Option to change port protocol
  3. Select the protocol needed for this port. The protocol that you select will be remembered for this port for the lifetime of the codespace.

Sharing a port

Note: You can only make a port private to an organization if your organization uses GitHub Team or GitHub Enterprise Cloud.

If you want to share a forwarded port with others, you can either make the port private to your organization or make the port public. After you make a port private to your organization, anyone in the organization with the port's URL can view the running application. After you make a port public, anyone who knows the URL and port number can view the running application without needing to authenticate.

Note: Your choice of port visibility options may be limited by a policy configured for your organization. For more information, see "Restricting the visibility of forwarded ports."

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Right click the port that you want to share, select the "Port Visibility" menu, then click Private to Organization or Public. Option to select port visibility in right-click menu
  3. To the right of the local address for the port, click the copy icon. Copy icon for port URL
  4. Send the copied URL to the person you want to share the port with.

Labeling a port

When you open a codespace in the browser, or in the VS Code desktop application, you can label a forwarded port to make it easier to identify in a list.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Hover over the port you want to label, then click the label icon. Label icon for port
  3. Type a label for your port, then press enter. Text box to type label for port

Adding a port to the codespace configuration

You can add a forwarded port to the GitHub Codespaces configuration for the repository, so the port will automatically be forwarded for all codespaces created from the repository. After you update the configuration, any previously created codespaces must be rebuilt for the change to apply. For more information, see "Introduction to dev containers."

You can manually configure forwarded ports in a .devcontainer.json file using the forwardPorts property, or you can use the "Ports" panel in a codespace that you've opened in the browser or the VS Code desktop application.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Right click the port you want to add to the codespace configuration, then click Set Label and Update devcontainer.json. Option to set label and add port to devcontainer.json in the right-click menu
  3. Type a label for your port, then press enter. Text box to type label for port

When an application running inside a codespace prints output to the terminal that contains a localhost URL, such as http://localhost:PORT or http://127.0.0.1:PORT, the port is automatically forwarded. If you're using GitHub Codespaces in the browser or in Visual Studio Code, the URL string in the terminal is converted into a link that you can click to view the web page on your local machine. By default, GitHub Codespaces forwards ports using HTTP.

Automatic port forwarding

You can also forward a port manually, label forwarded ports, share forwarded ports with members of your organization, share forwarded ports publicly, and add forwarded ports to the codespace configuration.

Note: Organization owners can restrict the ability to make forward ports available publicly or within the organization. For more information, see "Restricting the visibility of forwarded ports."

Forwarding a port

You can manually forward a port that wasn't forwarded automatically.

  1. In your codespace, under the text editor, click "Ports". Ports tab

  2. Under the list of ports, click Add port.

    Add port button

  3. Type the port number or address, then press enter.

    Text box to type port button

Sharing a port

Note: You can only make a port private to an organization if your organization uses GitHub Team or GitHub Enterprise Cloud.

If you want to share a forwarded port with others, you can either make the port private to your organization or make the port public. After you make a port private to your organization, anyone in the organization with the port's URL can view the running application. After you make a port public, anyone who knows the URL and port number can view the running application without needing to authenticate.

Note: Your choice of port visibility options may be limited by a policy configured for your organization. For more information, see "Restricting the visibility of forwarded ports."

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Right click the port that you want to share, select the "Port Visibility" menu, then click Private to Organization or Public. Option to make port public in right-click menu
  3. To the right of the local address for the port, click the copy icon. Copy icon for port URL
  4. Send the copied URL to the person you want to share the port with.

Labeling a port

When you open a codespace in the browser, or in the VS Code desktop application, you can label a forwarded port to make it easier to identify in a list.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Hover over the port you want to label, then click the label icon. Label icon for port
  3. Type a label for your port, then press enter. Text box to type label for port

Adding a port to the codespace configuration

You can add a forwarded port to the GitHub Codespaces configuration for the repository, so the port will automatically be forwarded for all codespaces created from the repository. After you update the configuration, any previously created codespaces must be rebuilt for the change to apply. For more information, see "Introduction to dev containers."

You can manually configure forwarded ports in a .devcontainer.json file using the forwardPorts property, or you can use the "Ports" panel in a codespace that you've opened in the browser or the VS Code desktop application.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Right click the port you want to add to the codespace configuration, then click Set Label and Update devcontainer.json. Option to set label and add port to devcontainer.json in the right-click menu
  3. Type a label for your port, then press enter. Text box to type label for port

To learn more about GitHub CLI, see "About GitHub CLI."

To forward a port use the gh codespace ports forward subcommand. Replace codespace-port:local-port with the remote and local ports that you want to connect. After entering the command choose from the list of codespaces that's displayed.

gh codespace ports forward CODESPACE-PORT:LOCAL-PORT

For more information about this command, see the GitHub CLI manual.

To see details of forwarded ports enter gh codespace ports and then choose a codespace.

Sharing a port

Note: You can only make a port private to an organization if your organization uses GitHub Team or GitHub Enterprise Cloud.

If you want to share a forwarded port with others, you can either make the port private to your organization or make the port public. After you make a port private to your organization, anyone in the organization with the port's URL can view the running application. After you make a port public, anyone who knows the URL and port number can view the running application without needing to authenticate.

Note: Your choice of port visibility options may be limited by a policy configured for your organization. For more information, see "Restricting the visibility of forwarded ports."

To change the visibility of a forwarded port, use the gh codespace ports visibility subcommand. There are three visibility settings:

  • private - Visible only to you. This is the default setting when you forward a port.
  • org - Visible to members of the organization that owns the repository.
  • public - Visible to anyone who knows the URL and port number.

Replace codespace-port with the forwarded port number. Replace setting with private, org, or public. After entering the command choose from the list of codespaces that's displayed.

gh codespace ports visibility CODESPACE-PORT:SETTINGS

You can set the visibility for multiple ports with one command. For example:

gh codespace ports visibility 80:private 3000:public 3306:org

For more information about this command, see the GitHub CLI manual.

Labeling a port

When you open a codespace in the browser, or in the VS Code desktop application, you can label a forwarded port to make it easier to identify in a list.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Hover over the port you want to label, then click the label icon. Label icon for port
  3. Type a label for your port, then press enter. Text box to type label for port

You can see the port labels when you list the forwarded ports for a codespace. To do this, use the gh codespace ports command and then select a codespace.

Adding a port to the codespace configuration

You can add a forwarded port to the GitHub Codespaces configuration for the repository, so the port will automatically be forwarded for all codespaces created from the repository. After you update the configuration, any previously created codespaces must be rebuilt for the change to apply. For more information, see "Introduction to dev containers."

You can manually configure forwarded ports in a .devcontainer.json file using the forwardPorts property, or you can use the "Ports" panel in a codespace that you've opened in the browser or the VS Code desktop application.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Right click the port you want to add to the codespace configuration, then click Set Label and Update devcontainer.json. Option to set label and add port to devcontainer.json in the right-click menu
  3. Type a label for your port, then press enter. Text box to type label for port

Forwarding a port

For information on how to forward a port in a codespace to a port on your local machine, see the "Port forwarding" section of the "Security model" article in the JetBrains documentation.

Alternatively, you can use GitHub CLI to forward a port. For more information, click the "GitHub CLI" tab at the top of this page.