About • Demo • Features • Use-cases • Access • Architecture • Deployment • FAQs

About

EXPOSE is your new favourite open source tool for exposing your local services on the public Internet with no installation or configuration required. EXPOSE relies on your SSH client and authenticates using the public SSH keys you have on your GitHub account.

To expose localhost:3000, simply type:

ssh -R 1:localhost:3000 expose.sh

If your computer username differs from your GitHub username:

ssh -R 1:localhost:3000 [email protected]

Demo

expose_demo.mp4

Features

• Nothing to install: use only your terminal and SSH client
• Nothing to configure: automatically retrieve public SSH keys from your GitHub account
• Custom URL: based on your GitHub username
• QR code generation: for easy mobile testing
• Multiple tunnels: up to 5 simultaneous services per account
• Distributed system: global routing for fastest access worldwide
• Secure: SSH encryption with automatic HTTPS certificates
• Open source: fully transparent

Use-cases

• Demos and presentations: access your applications from any internet-connected device
• Mobile development: expose local backends for Android/iOS app testing
• Webhook testing: test webhooks from payment gateways, messaging platforms, and APIs
• Cross-device testing: ensure your application works on all device types
• Development sharing: quickly share work-in-progress with team members

Access

To prevent malicious use, you must star this repository to access EXPOSE.
Authentication is handled through your GitHub SSH keys.

Tunnel allocation:

• Tunnels 1-3: Named as username, username-2, username-3, etc.
• Tunnels 4-5: Random names like username-x7k2m9
• Maximum: 5 concurrent tunnels per user
• Session limit: 2 hours (reconnectable unlimited times)

Architecture

EXPOSE consists of three containerized components deployed globally using Fly.io:

SSH Server (Python)

• Handles SSH connections and authentication
• Validates GitHub SSH keys and stargazer status
• Manages tunnel creation with slot-based naming
• Enforces connection limits and timeouts
• Creates Unix socket forwarding for local services

Tools Service (Node.js)

• Acts as intermediary between SSH server and web server
• Manages GitHub API integration with caching
• Generates QR codes for tunnel URLs
• Handles cache management across distributed instances
• Serves local banner content

Web Server (OpenResty/Nginx)

• Routes traffic to appropriate tunnels based on subdomains
• Handles caching and load balancing
• Provides HTTPS termination with automatic certificates
• Manages WebSocket upgrades

Deployment

Prerequisites

Generate an SSH key pair:

ssh-keygen -t ed25519 -f ./ssh_key -N ""

Configuration

1. Copy the example configuration:

cp fly.toml.example fly.toml

2. Update the required configuration fields:

app = 'your-app-name'
primary_region = 'cdg'  # Choose your preferred region

[env]
  FLYDOTIO_APP_NAME = 'your-app-name'
  HTTP_URL = 'yourdomain.com'
  SSH_SERVER_URL = 'ssh.yourdomain.com'
  GITHUB_REPOSITORY = 'gaetanlhf/EXPOSE'

3. Configure optional settings:
   • Adjust NAMED_TUNNELS_RANGE and RANDOM_TUNNELS_RANGE for tunnel allocation
   • Set TIMEOUT for session duration (in minutes)
   • Modify LOG_LEVEL for debugging (DEBUG, INFO, WARNING, ERROR)

Deploy to Fly.io

1. Launch the application:

fly launch

2. Add the SSH private key secret:

fly secrets set SSH_SERVER_KEY="$(cat ssh_key)"

3. Configure DNS to point your domains to Fly.io's IPv4 and IPv6 addresses

4. Add HTTPS certificates in the Fly.io dashboard for your domains

Configuration Variables

Required Variables

Variable	Description	Example
app	Fly.io application name	my-expose-server
primary_region	Fly.io deployment region	cdg, lax, fra
FLYDOTIO_APP_NAME	Must match the app name	my-expose-server
HTTP_URL	Domain for tunnel URLs	expos.es
SSH_SERVER_URL	SSH connection endpoint	expose.sh
GITHUB_REPOSITORY	Repository to check for stargazers	gaetanlhf/EXPOSE

Optional Variables

Variable	Default	Description
NAMED_TUNNELS_RANGE	1-3	Slots for username-based naming
RANDOM_TUNNELS_RANGE	4-5	Slots for random naming
TIMEOUT	120	Session timeout in minutes
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
SSH_SERVER_PORT	2222	Internal SSH server port
NODEJS_TOOLS_PORT	3000	Internal tools service port

Usage Examples

Single tunnel:

ssh -R 1:localhost:3000 expose.sh

Multiple tunnels:

ssh -R 1:localhost:3000 -R 2:localhost:8080 expose.sh

Auto-reconnect:

until ssh -R 1:localhost:3000 expose.sh; do echo "Reconnecting..."; done

FAQs

Is EXPOSE secure?

Yes, SSH is an encrypted protocol, and access to your application is secure thanks to automatic HTTPS certificates.

What do you mean by no installation and no configuration?

No installation because EXPOSE uses your existing SSH client. No configuration because EXPOSE automatically retrieves data from your SSH client and GitHub account.

How many tunnels can I create simultaneously?

You can create up to 10 simultaneous tunnels. Slots 1-3 use your username, slots 4-5 use your username + random chars.

What's the session time limit?

Each session lasts up to 2 hours, but you can reconnect unlimited times.

I see "Cannot connect to your local application" in the browser

Ensure your local application is running and accessible at `http://localhost:port`.

I see "connect_to localhost port failed" in terminal

Verify your local service is running on the specified port by testing `http://localhost:port` in your browser.

Does EXPOSE support other protocols?

EXPOSE supports HTTP, HTTPS, and WebSocket protocols.

Where can I get help?

Open an issue on this repository or send an email to [email protected].

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.