Forwarding ports in your codespace

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.

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.

Forwarding a port

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

1. Open the terminal in your codespace.

2. Click the PORTS tab.

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

   

4. Type the port number or address, then press Enter.

   

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. Open the terminal in your codespace.

2. Click the PORTS tab.

3. Right-click the port you want to update, then hover over Change Port Protocol.

   

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

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.

1. Open the terminal in your codespace.

2. Click the PORTS tab.

3. Right-click the port that you want to share, click the Port Visibility, then click Private to Organization or Public.

   

4. To the right of the local address for the port, click the copy icon.

   

5. Send the copied URL to the person you want to share the port with.

Using command-line tools and REST clients to access ports

When you forward a port, your application becomes available at a URL such as https://USERNAME-CODESPACE-NAME-vrpqrxxrx7x2rxx-4000.preview.app.github.dev. If you forward a private port from the VS Code desktop application, your application will also be available at a localhost port such as 127.0.0.1:4000.

To access your application using a REST client, such as Postman, or a command-line tool like curl, you don't need to authenticate if you're using a localhost port, or if you're accessing a public port at the remote domain. However, to connect to a private port at the remote domain, you must authenticate by using the GITHUB_TOKEN access token in your request.

Finding the address to connect to

1. Open the terminal in your codespace.

2. Click the PORTS tab. This lists all of the ports you have forwarded.

3. Right-click the port you want to connect to and click Copy Local Address.

   

4. Paste the copied address somewhere for later use.

Finding the GITHUB_TOKEN

1. In the terminal in your codespace, enter echo $GITHUB_TOKEN.

   The token is a string beginning ghu_.

2. Copy the token.

   Important: Don't share this access token with anyone.

Using curl to access a forwarded port

In a terminal on your local computer, enter:

curl ADDRESS -H "X-Github-Token: TOKEN"

Replace ADDRESS and TOKEN with the values you copied previously.

Using Postman to access a forwarded port

1. Open Postman.

2. Create a new GET request.

3. Paste the address you copied previously as the request URL.

   

4. In the Headers tab, create a new entry where the key is "X-Github-Token" and the value is the GITHUB_TOKEN you copied previously.

   

5. Click Send.

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. Open the terminal in your codespace.

2. Click the PORTS tab.

3. Hover over the port you want to label, then click the label icon.

4. Type a label for your port, then press Enter.

   

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. Open the terminal in your codespace.

2. Click the PORTS tab.

3. Right click the port you want to add to the codespace configuration, then click Set Label and Update devcontainer.json.

   

4. Type a label for your port, then press Enter.