Port sharing allows you to expose ports from your running Ona environment to the internet, enabling easy sharing and collaboration. This feature supports both HTTP and HTTPS communication and is available for cloud-hosted Ona environments not Gitpod Desktop environments.

​
How it works

When you share a port, Ona creates a public URL with automatic TLS termination. Ona handles incoming HTTPS connections and forwards them to your service using either HTTP or HTTPS protocol, depending on your configuration.

​
Protocol Support

When sharing a port, you can configure how Ona communicates with your service:
  • HTTP (default): Standard HTTP communication to your service
  • HTTPS: Secure HTTPS communication for services requiring SSL/TLS connections
All public URLs use HTTPS encryption. The protocol setting only affects how Ona connects to your service within the environment.

​
Limitations

  • Not available on Gitpod Desktop environments.
  • Subject to Ona’s fair use policies and bandwidth limits.

​
Prerequisites

To ensure port sharing works correctly, services must:
  • listen on 0.0.0.0 instead of localhost or 127.0.0.1
  • be exposed from the Dev Container on the virtual machine using the host network stack.
For example, if you’re running a Node.js server, make sure to bind it to 0.0.0.0 instead of localhost. 
const app = express();
app.listen(3000, '0.0.0.0', () => {
	console.log('Server is running on port 3000');
});

​
Security considerations

While port sharing is convenient, it’s important to be mindful of security:
  • Only share ports when necessary and unshare them when you’re done.
  • Be cautious about sharing ports running sensitive services or containing confidential data.
  • Remember that shared URLs are public and potentially accessible by anyone with the link.

​
Sharing ports

There are two ways to share ports from your Gitpod environment:

​
Using the UI

In the Ona UI, you’ll see a section labeled “Public Ports” that allows you to manage port sharing for your environment. To share a new port:
  1. Click the “Open Port” button in the “Public Ports” section.
  2. A dialog will appear titled “Open a public port”.
  3. Enter a name for the port (optional) and the port number you wish to share.
  4. Select the protocol (HTTP or HTTPS) for service communication.
  5. Click “Open Port” to confirm.
For ports that are already open: They will be listed in the “Public Ports” section. Each open port will show its name (if given), port number, and protocol. A green indicator next to the port signifies it’s currently active and accessible.
Security notice: When you open a port, it will be available on the open internet. Be careful when sharing the URL.
This interface provides an easy way to manage which ports are exposed from your Ona environment, allowing you to quickly share access to services or applications you’re running.

​
Using the CLI

The Gitpod CLI provides a set of commands to manage port sharing. These commands allow you to list, open, and close ports directly from your terminal.

​
Listing ports

To view all currently open ports: 
gitpod environment port list
This command will display a list of all ports that are currently open and available for sharing.

​
Opening a Port

To open and share a new port: 
gitpod environment port open 3000 --name my-app
To open a port with HTTPS protocol: 
gitpod environment port open 3000 --name my-app --protocol https
The --protocol flag accepts:
  • http (default): Standard HTTP communication
  • https: Secure HTTPS communication

​
Closing a Port

To close a previously opened port: 
gitpod environment port close <port-number>
For example, to close port 3000: 
gitpod environment port close 3000

​
Examples

  1. Open a port for a web server: 
    gitpod environment port open 8080 --name webserver
  2. Open a port for an API server: 
    gitpod environment port open 4000 --name api
  3. Open a port for a development server that requires HTTPS: 
    gitpod environment port open 3000 --name dev-server --protocol https
  4. List all open ports: 
    gitpod environment port list
  5. Close a port that’s no longer needed: 
    gitpod environment port close 4000
These CLI commands provide a quick and efficient way to manage port sharing directly from your terminal, especially useful for scripting or when you prefer command-line interactions.

​
Use cases

Port sharing enables various scenarios that enhance development workflows and collaboration:
  1. Demonstrating work-in-progress: Quickly share your application with teammates or clients without deploying to a staging environment.
  2. API testing: Expose your development API server to test integrations with external services or mobile apps.
  3. Collaborative debugging: Share a running application with a colleague to troubleshoot issues together in real-time.
  4. Design reviews: Make your development server accessible so designers can review and provide feedback on UI changes.
  5. Webhooks development: Test webhook integrations by exposing your server to receive real-time events from external services.
  6. HTTPS-dependent applications: Test applications that require HTTPS protocol, such as:
    • Applications with HTTPS-only policies or redirects
    • Streaming APIs requiring secure connections
    • Integration with external services requiring HTTPS callbacks