Forwarding ports in your codespace

You can forward ports in your codespace to test and debug your application.

Codespaces is available for user accounts using GitHub Free or GitHub Pro. For more information, see "GitHub's products."

In this article

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 port 4000, you can access the application from your browser to test and debug the application.

When an application running inside a codespace outputs a port to the console, Codespaces detects the localhost URL pattern and automatically forwards the port. You can click on the URL in the terminal to open the port in a browser. For example, if an application outputs http://127.0.0.1:4000 or http://localhost:4000 to the console, the log would automatically convert the output to a clickable URL for port 4000.

Automatic port forwarding

You can also forward a port manually, label forwarded ports, share fowarded ports publicly, and add forwarded ports to the codespace configuration.

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

Labeling a port

You can label a port to make the port more easily identifiable 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

Sharing a port

If you want to share a forwarded port with others, you can make the port public. After you make a port public, anyone with the port's URL can view the running application without needing to authenticate.

  1. In your codespace, under the text editor, click "Ports". Ports tab
  2. Right click the port you want to share, then click Make 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.

Adding a port to the codespace configuration

You can add a forwarded port to the 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 "Configuring Codespaces for your project."

You can manually configure fowarded ports in a .devcontainer.json file using the forwardPorts property, or you can use the "Ports" panel in your codespace.

  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

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.