plain.tunnel
Expose your local development server to the internet.
Overview
Plain Tunnel is a hosted tunneling service that gives your local development server a public URL. You can use it to test webhooks from third-party services, preview your site on a mobile device, or share your work with someone temporarily.
To create a tunnel, run:
plain tunnel https://app.localhost:8443
This connects your local server to a randomly generated subdomain like yourname-abc1234.plaintunnel.com. The tunnel stays open until you stop it with Ctrl+C.
To use a consistent subdomain, pass the --subdomain option:
plain tunnel https://app.localhost:8443 --subdomain myapp
Now your tunnel will always be available at https://myapp.plaintunnel.com.
Integrating with plain.dev
You can run the tunnel automatically alongside your development server by adding it to your pyproject.toml:
[tool.plain.dev.run]
tunnel = {cmd = "plain tunnel $DEV_URL --subdomain myapp --quiet"}
The $DEV_URL variable is automatically set to your local server URL. The --quiet flag reduces log output so it does not clutter your terminal.
To display the tunnel URL in the plain dev header, add DEV_TUNNEL_URL to your .env file:
DEV_TUNNEL_URL=https://myapp.plaintunnel.com
CLI options
The cli command accepts these options:
| Option | Description |
|---|---|
destination |
URL of your local server (required) |
--subdomain |
Custom subdomain to use |
--debug |
Enable debug logging |
--quiet |
Only log warnings and errors |
Examples:
# With debug logging to troubleshoot connection issues
plain tunnel https://app.localhost:8443 --debug
# Run as a standalone tool without installing
uvx plain-tunnel https://app.localhost:8443
Environment variables
You can configure the tunnel using environment variables instead of CLI options:
| Variable | Description |
|---|---|
PLAIN_TUNNEL_SUBDOMAIN |
Default subdomain to use |
PLAIN_TUNNEL_HOST |
Tunnel host (defaults to plaintunnel.com) |
FAQs
How does the tunnel work?
The tunnel establishes a WebSocket connection to the Plain Tunnel server. When a request arrives at your public URL, the server forwards it through the WebSocket to your local machine. The TunnelClient then makes the request to your local server and sends the response back.
What happens if the connection drops?
The tunnel automatically reconnects if the connection is lost. It will retry up to 5 times with a 2-second delay between attempts.
Can I use this without installing Plain?
Yes. You can run the tunnel as a standalone tool using uvx:
uvx plain-tunnel https://localhost:8000
Do I need to configure ALLOWED_HOSTS?
If you are using Plain with a custom subdomain, you may need to add it to your ALLOWED_HOSTS setting:
# app/settings.py
ALLOWED_HOSTS = [
"localhost",
"app.localhost",
"myapp.plaintunnel.com",
]
Installation
Install from PyPI:
uv add plain.tunnel --dev
Then run the tunnel:
plain tunnel https://app.localhost:8443
1 maintainer
Metadata
1 maintainer
Release files for plain.tunnel 0.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| plain_tunnel-0.13.0.tar.gz | 35.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| plain_tunnel-0.13.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 51.3 kB
Release files / plain_tunnel-0.13.0.tar.gz
| Download URL | plain_tunnel-0.13.0.tar.gz |
|---|---|
| Size | 35.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4ec85dfa7e12dd894d3dac7c97f9002a9d5217d95063313e4ef6192ffb129c44
|
|
BLAKE2b-256 checksum How to use checksums |
27b428ebd0cd0512da76c1247987c6b5b2eabbf4b44957e57438dc857c6a947c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / plain_tunnel-0.13.0-py3-none-any.whl
| Download URL | plain_tunnel-0.13.0-py3-none-any.whl |
|---|---|
| Size | 15.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
96552ad170b0957258ae256d26f87f3e88506b591a3e2323009706a10fb7f9a5
|
|
BLAKE2b-256 checksum How to use checksums |
184095e194b205ad987bef4ea2a88e8cb11bc4ad5e6efbc9d50af13baa2a358d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
