Metadata-Version: 2.4
Name: remote-local
Version: 0.0.2
Summary: Expose your local FastAPI, NiceGUI, or development servers remotely — easily, reliably, and for free.
Home-page: https://github.com/puntorigen/remote-local
Author: Pablo Schaffner
Author-email: Pablo Schaffner <pablo@puntorigen.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/puntorigen/remote-local
Project-URL: Source, https://github.com/puntorigen/remote-local
Project-URL: Documentation, https://github.com/puntorigen/remote-local
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Framework :: FastAPI
Classifier: Framework :: AsyncIO
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyngrok>=5.3.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: fastapi>=0.100.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# remote-local

Expose your local FastAPI, NiceGUI, or development servers remotely — easily, reliably, and for free.

**remote-local** is a simple and robust middleware that automatically creates a public tunnel for your local server using ngrok (and more in the future).  
It handles session cleanup, hot reloads, and retries automatically — no manual setup required.

---

## Features

- 🌍 Expose your local server remotely with **one line of code**.
- ⚡ Fully compatible with **FastAPI**, **NiceGUI**, or any **ASGI app**.
- 🔄 **Handles hot reloads** and session recovery automatically.
- 🔒 **No external configuration** required — works with free ngrok accounts.
- 🛠️ Designed for **development, testing, and remote integrations**.

---

## Installation

```bash
pip install remote-local
```

---

## Quick Usage

```python
from nicegui import app, ui
from remote_local import NgrokMiddleware

NgrokMiddleware(app, port=8080)

@ui.page('/')
async def main_page():
    ui.label('Hello World')

ui.run(port=8080, reload=True)
```

✅ That's it! Your local server is now publicly accessible through a secure URL.

By default, a `/server-info` endpoint is also created, showing the current public URL and server status.

---

## Environment Variable: PUBLIC_URL

If your server is already running with a public URL (for example, in a production deployment), you can set the `PUBLIC_URL` environment variable. When `PUBLIC_URL` is set, the middleware will **skip starting ngrok** and use the provided URL as the public-facing address for your app.

- If `PUBLIC_URL` is set, ngrok will **not** be started and the middleware will simply use this value.
- If `PUBLIC_URL` is not set, the middleware will start ngrok and set the public URL automatically.

Example:

```bash
export PUBLIC_URL=https://your-production-url.example.com
```

---

## Configuration Options

You can customize the middleware:

```python
NgrokMiddleware(
    app,
    port=8080,
    max_wait_seconds=60,    # how long to retry if ngrok fails initially
    fallback_to_localhost=False,  # fallback to localhost if ngrok fails
    expose_server_info=True,      # create a /server-info endpoint
)
```

---

## License

This project is licensed under the [MIT License](LICENSE).

---

## Future Plans

- Support for other tunnels (Cloudflared, Localhost.run, etc.)
- More flexible server info APIs
- Auto-detection of multiple servers

---

## Author

Made with ❤️ by Pablo Schaffner
