{"meta":{"title":"Forwarding ports in your codespace","intro":"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.","product":"Codespaces","breadcrumbs":[{"href":"/en/codespaces","title":"Codespaces"},{"href":"/en/codespaces/developing-in-a-codespace","title":"Developing in a codespace"},{"href":"/en/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace","title":"Forward ports"}],"documentType":"article"},"body":"# Forwarding ports in your codespace\n\nYou 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.\n\n## About forwarded ports\n\nPort 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.\n\n\n\nWhen 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.\n\nYou can edit the dev container configuration for the repository to automatically forward one or more ports. 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.\n\n> \\[!NOTE]\n> 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](/en/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports).\n\n## Forwarding a port\n\nYou can manually forward a port that wasn't forwarded automatically.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Under the list of ports, click **Add port**.\n\n \n\n4. Type the port number or address, then press Enter.\n\n \n\n## Using HTTPS forwarding\n\nBy 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.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port you want to update, then hover over **Change Port Protocol**.\n\n \n\n4. Select the protocol needed for this port. The protocol that you select will be remembered for this port for the lifetime of the codespace.\n\n## Sharing a port\n\n> \\[!NOTE]\n> You can only make a port private to an organization if your organization uses GitHub Team or GitHub Enterprise Cloud.\n\nIf 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.\n\n> \\[!NOTE]\n> 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](/en/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports).\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port that you want to share, click the **Port Visibility**, then click **Private to Organization** or **Public**.\n\n \n\n4. To the right of the local address for the port, click the copy icon.\n\n \n\n5. Send the copied URL to the person you want to share the port with.\n\n## Using command-line tools and REST clients to access ports\n\nWhen you forward a port, your application becomes available at the URL `https://CODESPACENAME-PORT.app.github.dev`. For example, `https://monalisa-hot-potato-vrpqrxxrx7x2rxx-4000.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`.\n\nTo 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.\n\n> \\[!NOTE]\n> The `GITHUB_TOKEN` is automatically created when you start a codespace and remains the same for the duration of the codespace session. If you stop and then restart a codespace a new `GITHUB_TOKEN` is generated.\n\n\n\n### Finding the address to connect to\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab. This lists all of the ports you have forwarded.\n\n3. Right-click the port you want to connect to and click **Copy Local Address**.\n\n \n\n4. Paste the copied address somewhere for later use.\n\n### Finding the GITHUB\\_TOKEN\n\n1. In the terminal in your codespace, enter `echo $GITHUB_TOKEN`.\n\n The token is a string beginning `ghu_`.\n\n2. Copy the token.\n\n > \\[!IMPORTANT]\n > Don't share this access token with anyone.\n\n### Using curl to access a forwarded port\n\nIn a terminal on your local computer, enter:\n\n```shell\ncurl ADDRESS -H \"X-Github-Token: TOKEN\"\n```\n\nReplace `ADDRESS` and `TOKEN` with the values you copied previously.\n\n### Using Postman to access a forwarded port\n\n1. Open Postman.\n\n2. Create a new GET request.\n\n3. Paste the address you copied previously as the request URL.\n\n \n\n4. 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.\n\n \n\n5. Click **Send**.\n\n## Automatically forwarding a port\n\nYou can add a forwarded port to the GitHub Codespaces configuration for the repository, so that the port will be automatically 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 about the dev container configuration file, see [Introduction to dev containers](/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace).\n\n1. In your codespace, open the dev container configuration file you want to update. Typically this file is `.devcontainer/devcontainer.json`.\n\n2. Add the `forwardPorts` property.\n\n ```json\n \"forwardPorts\": [NUMBER],\n ```\n\n Replace `NUMBER` with the port number you want to forward. This can be a comma-separated list of port numbers.\n\n3. Save the file.\n\n## Labeling a port\n\nWhen 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.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port you want to label, then click **Set Port Label**.\n\n \n\n4. Type a label for your port, then press Enter.\n\n \n\n### Automatically labeling a forwarded port\n\nYou can label a port and write the change to a dev container configuration file for the repository. If you do this for a port that is automatically forwarded, using the `forwardPorts` property, then the label will be automatically applied to that forwarded port for all future codespaces created from the repository using that configuration file.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port whose label attribute you want to add to the codespace configuration, then click **Set Label and Update devcontainer.json**.\n\n \n\n4. Type a label for your port, then press Enter.\n\n \n\n5. If your repository has more than one dev container configuration file, you will be prompted to choose which file you want to update.\n\n The dev container configuration file is updated to include the new label in the `portsAttributes` property. For example:\n\n ```jsonc\n // Use 'forwardPorts' to make a list of ports inside the container available locally.\n \"forwardPorts\": [3333, 4444],\n\n \"portsAttributes\": {\n \"3333\": {\n \"label\": \"app-standard-preview\"\n },\n \"4444\": {\n \"label\": \"app-pro-preview\"\n }\n }\n ```\n\n
\n\n\n\nWhen 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.\n\nYou can edit the dev container configuration for the repository to automatically forward one or more ports. 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.\n\n> \\[!NOTE]\n> 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](/en/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports).\n\n## Forwarding a port\n\nYou can manually forward a port that wasn't forwarded automatically.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Under the list of ports, click **Add port**.\n\n \n\n4. Type the port number or address, then press Enter.\n\n \n\n## Sharing a port\n\n> \\[!NOTE]\n> You can only make a port private to an organization if your organization uses GitHub Team or GitHub Enterprise Cloud.\n\nIf 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.\n\n> \\[!NOTE]\n> 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](/en/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports).\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port that you want to share, click **Port Visibility**, then click **Private to Organization** or **Public**.\n\n \n\n4. To the right of the local address for the port, click the copy icon.\n\n \n\n5. Send the copied URL to the person you want to share the port with.\n\n## Using command-line tools and REST clients to access ports\n\nWhen you forward a port, your application becomes available at the URL `https://CODESPACENAME-PORT.app.github.dev`. For example, `https://monalisa-hot-potato-vrpqrxxrx7x2rxx-4000.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`.\n\nTo 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.\n\n> \\[!NOTE]\n> The `GITHUB_TOKEN` is automatically created when you start a codespace and remains the same for the duration of the codespace session. If you stop and then restart a codespace a new `GITHUB_TOKEN` is generated.\n\n\n\n### Finding the address to connect to\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab. This lists all of the ports you have forwarded.\n\n3. Right-click the port you want to connect to and click **Copy Local Address**.\n\n \n\n4. Paste the copied address somewhere for later use.\n\n### Finding the GITHUB\\_TOKEN\n\n1. In the terminal in your codespace, enter `echo $GITHUB_TOKEN`.\n\n The token is a string beginning `ghu_`.\n\n2. Copy the token.\n\n > \\[!IMPORTANT]\n > Don't share this access token with anyone.\n\n### Using curl to access a forwarded port\n\nIn a terminal on your local computer, enter:\n\n```shell\ncurl ADDRESS -H \"X-Github-Token: TOKEN\"\n```\n\nReplace `ADDRESS` and `TOKEN` with the values you copied previously.\n\n### Using Postman to access a forwarded port\n\n1. Open Postman.\n\n2. Create a new GET request.\n\n3. Paste the address you copied previously as the request URL.\n\n \n\n4. 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.\n\n \n\n5. Click **Send**.\n\n## Automatically forwarding a port\n\nYou can add a forwarded port to the GitHub Codespaces configuration for the repository, so that the port will be automatically 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 about the dev container configuration file, see [Introduction to dev containers](/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace).\n\n1. In your codespace, open the dev container configuration file you want to update. Typically this file is `.devcontainer/devcontainer.json`.\n\n2. Add the `forwardPorts` property.\n\n ```json\n \"forwardPorts\": [NUMBER],\n ```\n\n Replace `NUMBER` with the port number you want to forward. This can be a comma-separated list of port numbers.\n\n3. Save the file.\n\n## Labeling a port\n\nWhen 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.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port you want to label, then click **Set Port Label**.\n\n \n\n4. Type a label for your port, then press Enter.\n\n \n\n### Automatically labeling a forwarded port\n\nYou can label a port and write the change to a dev container configuration file for the repository. If you do this for a port that is automatically forwarded, using the `forwardPorts` property, then the label will be automatically applied to that forwarded port for all future codespaces created from the repository using that configuration file.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port whose label attribute you want to add to the codespace configuration, then click **Set Label and Update devcontainer.json**.\n\n \n\n4. Type a label for your port, then press Enter.\n\n \n\n5. If your repository has more than one dev container configuration file, you will be prompted to choose which file you want to update.\n\n The dev container configuration file is updated to include the new label in the `portsAttributes` property. For example:\n\n ```jsonc\n // Use 'forwardPorts' to make a list of ports inside the container available locally.\n \"forwardPorts\": [3333, 4444],\n\n \"portsAttributes\": {\n \"3333\": {\n \"label\": \"app-standard-preview\"\n },\n \"4444\": {\n \"label\": \"app-pro-preview\"\n }\n }\n ```\n\n
\n\n\n\n> \\[!NOTE]\n> To learn more about GitHub CLI, see [About GitHub CLI](/en/github-cli/github-cli/about-github-cli).\n\nTo 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.\n\n```shell\ngh codespace ports forward CODESPACE-PORT:LOCAL-PORT\n```\n\nFor more information about this command, see [the GitHub CLI manual](https://cli.github.com/manual/gh_codespace_ports_forward).\n\nTo see details of forwarded ports enter `gh codespace ports` and then choose a codespace.\n\n## Sharing a port\n\n> \\[!NOTE]\n> You can only make a port private to an organization if your organization uses GitHub Team or GitHub Enterprise Cloud.\n\nIf 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.\n\n> \\[!NOTE]\n> 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](/en/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports).\n\nTo change the visibility of a forwarded port, use the `gh codespace ports visibility` subcommand. There are three visibility settings:\n\n* `private` - Visible only to you. This is the default setting when you forward a port.\n* `org` - Visible to members of the organization that owns the repository.\n* `public` - Visible to anyone who knows the URL and port number.\n\nReplace `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.\n\n```shell\ngh codespace ports visibility CODESPACE-PORT:SETTINGS\n```\n\nYou can set the visibility for multiple ports with one command. For example:\n\n```shell\ngh codespace ports visibility 80:private 3000:public 3306:org\n```\n\nFor more information about this command, see [the GitHub CLI manual](https://cli.github.com/manual/gh_codespace_ports_visibility).\n\n## Using command-line tools and REST clients to access ports\n\nWhen you forward a port, your application becomes available at the URL `https://CODESPACENAME-PORT.app.github.dev`. For example, `https://monalisa-hot-potato-vrpqrxxrx7x2rxx-4000.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`.\n\nTo 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.\n\n> \\[!NOTE]\n> The `GITHUB_TOKEN` is automatically created when you start a codespace and remains the same for the duration of the codespace session. If you stop and then restart a codespace a new `GITHUB_TOKEN` is generated.\n\n\n\n### Finding the address to connect to\n\nTo find the address for a forwarded port, enter `gh codespace ports`. If you have more than one codespace, select the appropriate codespace from the list that's displayed.\n\nCopy the address and paste it somewhere for later use.\n\n### Finding the GITHUB\\_TOKEN\n\n1. Start an SSH session for your codespace.\n\n ```shell\n gh codespace ssh\n ```\n\n2. If you have more than one codespace, select the appropriate codespace from the list that's displayed.\n\n3. Display the `GITHUB_TOKEN`.\n\n ```shell\n echo $GITHUB_TOKEN\n ```\n\n The token is a string beginning `ghu_`.\n\n4. Copy the token.\n\n > \\[!IMPORTANT]\n > Don't share this access token with anyone.\n\n5. Exit the SSH session.\n\n ```shell\n exit\n ```\n\n### Using curl to access a forwarded port\n\nIn a terminal on your local computer, enter:\n\n```shell\ncurl ADDRESS -H \"X-Github-Token: TOKEN\"\n```\n\nReplace `ADDRESS` and `TOKEN` with the values you copied previously.\n\n### Using Postman to access a forwarded port\n\n1. Open Postman.\n\n2. Create a new GET request.\n\n3. Paste the address you copied previously as the request URL.\n\n \n\n4. 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.\n\n \n\n5. Click **Send**.\n\n## Automatically forwarding a port\n\nYou can add a forwarded port to the GitHub Codespaces configuration for the repository, so that the port will be automatically 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 about the dev container configuration file, see [Introduction to dev containers](/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace).\n\n1. In your codespace, open the dev container configuration file you want to update. Typically this file is `.devcontainer/devcontainer.json`.\n\n2. Add the `forwardPorts` property.\n\n ```json\n \"forwardPorts\": [NUMBER],\n ```\n\n Replace `NUMBER` with the port number you want to forward. This can be a comma-separated list of port numbers.\n\n3. Save the file.\n\n## Labeling a port\n\nWhen 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.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port you want to label, then click **Set Port Label**.\n\n \n\n4. Type a label for your port, then press Enter.\n\n \n\n### Automatically labeling a forwarded port\n\nYou can label a port and write the change to a dev container configuration file for the repository. If you do this for a port that is automatically forwarded, using the `forwardPorts` property, then the label will be automatically applied to that forwarded port for all future codespaces created from the repository using that configuration file.\n\n1. Open the terminal in your codespace.\n\n2. Click the **PORTS** tab.\n\n3. Right-click the port whose label attribute you want to add to the codespace configuration, then click **Set Label and Update devcontainer.json**.\n\n \n\n4. Type a label for your port, then press Enter.\n\n \n\n5. If your repository has more than one dev container configuration file, you will be prompted to choose which file you want to update.\n\n The dev container configuration file is updated to include the new label in the `portsAttributes` property. For example:\n\n ```jsonc\n // Use 'forwardPorts' to make a list of ports inside the container available locally.\n \"forwardPorts\": [3333, 4444],\n\n \"portsAttributes\": {\n \"3333\": {\n \"label\": \"app-standard-preview\"\n },\n \"4444\": {\n \"label\": \"app-pro-preview\"\n }\n }\n ```\n\n### Seeing port labels on the command line\n\nYou 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.\n\n
"}