Gateway Tunnel

README

# openclaw-gateway-tunnel

> An [openclaw](https://github.com/openclaw/openclaw) plugin that exposes the local gateway to the public internet — with zero external binaries, zero daemons, zero host changes. Install openclaw, install this plugin, done.

> [!WARNING]
> **Status: design phase, no code yet.** This repository contains an idea and a design document. It is opened publicly to gather feedback and co-designers **before** implementation starts. If you need a working solution today, use [cloudflared](https://github.com/cloudflare/cloudflared) or [Tailscale](https://tailscale.com/) directly.

## The problem

openclaw's gateway binds to loopback by default. Reaching it from outside the local network currently requires one of:

- Installing `cloudflared` and setting up a Cloudflare Tunnel (needs domain, account, binary)
- Installing Tailscale (needs daemon, user account)
- Running a reverse proxy / self-hosted relay (needs VPS + ops)

All of these require **additional tooling on the host**. This breaks the "install openclaw and it works" promise on restricted environments: managed VPS, locked-down Docker images, one-click deploy scripts, shared hosting, hosts with no sudo.

Many people running openclaw are doing so through a deployment provider where the only thing they can install is openclaw itself. For them, "make my gateway reachable from my phone" is currently unreachable.

## The idea

A standalone openclaw plugin, distributed via npm, that:

1. Runs **inside the openclaw process** as an `OpenClawPluginService`
2. Uses [`@ngrok/ngrok`](https://github.com/ngrok/ngrok-javascript) — ngrok's official Node SDK with a Rust core shipped as a napi-prebuilt native addon — to open a tunnel from the gateway port to a public ngrok endpoint
3. Requires **no external binary**, no separate daemon, no host-level install. If `npm install` works for openclaw, it works for this plugin.
4. Delegates all authentication, authorization, pairing, and access control back to openclaw. The plugin is a network-layer tool and nothing more.

The user's only one-time action is pasting an ngrok authtoken (free account). Everything else flows from the plugin's `start` / `stop` lifecycle.

## Why this shape

This project's scope is aggressively narrow by design. Things we **explicitly do not want**:

- ❌ Multiple provider backends (localtunnel, cloudflared, tunnelmole, …) — ngrok only
- ❌ General-purpose process supervision — single ngrok session, nothing more
- ❌ Any form of authentication, authorization, or access control — that's openclaw's job
- ❌ Automatic URL injection into pairing QR codes — v1 just logs the URL; users copy it where needed
- ❌ Becoming a VPN replacement — this is a SaaS tunnel wrapper, not a trust boundary

If you want multi-provider or P2P or end-to-end encryption, those belong in separate projects. See [`docs/DESIGN.md`](./docs/DESIGN.md) for the full non-goals list and the reasoning behind each cut.

## Security notes you must read

This plugin introduces a **third-party man-in-the-middle**. Your gateway traffic will traverse ngrok's edge, where TLS terminates. ngrok Inc. has technical visibility into request and response bodies unless openclaw itself applies end-to-end payload encryption above WebSocket.

This is **the same trust model** as Cloudflare Tunnel, Tailscale Funnel with TLS termination, or any other hosted reverse tunnel. It is not unique to ngrok. But you should understand it before using the plugin for anything sensitive.

Deployments handling regulated data, internal credentials, or anything where a SaaS provider reading your traffic is unacceptable should use a trusted overlay network instead.

Full security analysis: [`docs/DESIGN.md#security`](./docs/DESIGN.md#security).

## Current status

| | |
|---|---|
| **Phase** | Design / ideation |
| **Code** | None yet |
| **Design doc** | [`docs/DESIGN.md`](./docs/DESIGN.md) |
| **v0.1 target** | Minimum viable: start / stop / log public URL / degrade gracefully |
| **Looking for** | Feedback on the design, pushback on non-goals, platform testers (especially Alpine musl), contributors who want to co-own the v0.1 implementation |

Nothing is implemented. Nothing is pinned. Everything in the design doc is still up for discussion.

## How to get involved

**Right now, before any code is written, is the best time to shape this project.**

- 🗣️ **Open an issue** to propose changes, challenge assumptions, or ask questions about the design
- 💬 **Start a Discussion** if you have a broader topic that doesn't fit an issue (enable [GitHub Discussions](https://docs.github.com/en/discussions) on this repo)
- 📝 **Comment on [`docs/DESIGN.md`](./docs/DESIGN.md)** via a PR with inline suggestions
- 🧪 **Volunteer as a platform tester** for pre-release builds, especially on Alpine Linux / musl and ARM hosts
- 🛠️ **Claim an open question** — the design doc lists six open questions that need verification against openclaw's plugin SDK source. Picking one and posting your findings as an issue is a perfect first contribution.

No existing code to learn. No entrenched choices to argue against. This is a rare moment in an open source project's life — the blueprint is on the table and the pen is still passing around.

## Roadmap

- **v0.0 (now)** — design doc, open questions, community feedback
- **v0.1** — minimum viable plugin: lifecycle, ngrok SDK integration, config schema, secret resolution, logging
- **v0.2** — `gateway-tunnel login` / `status` CLI subcommands, documentation, Alpine verification
- **v0.3+** — only if user demand: ngrok IP restrictions, OAuth passthrough, structured events

See [`docs/DESIGN.md#milestones`](./docs/DESIGN.md#milestones) for the full breakdown.

## Relationship to openclaw

This is a **third-party plugin**, distributed independently from the openclaw monorepo. It depends on the public [openclaw plugin SDK](https://github.com/openclaw/openclaw) and will pin to a supported SDK version range.

This project is not affiliated with or endorsed by the openclaw maintainers. If the plugin proves valuable and stable, upstreaming conversations can happen later — but the default assumption is "independent third-party plugin, forever".

## License

[MIT](./LICENSE) — use it, fork it, ship it.

## Acknowledgements

- [openclaw](https://github.com/openclaw/openclaw) for making a plugin architecture worth building for
- [ngrok](https://ngrok.com/) for shipping a real Node SDK instead of just a binary wrapper