portal-tunnel
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gosuda/portal-tunnel with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gosuda/portal-tunnel'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/gosuda--portal-tunnel)HTML
<a href="/listings/gosuda--portal-tunnel"><img src="/api/listings/gosuda--portal-tunnel/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
1. Expose a local service
**macOS / Linux:**
curl -fsSL https://github.com/gosuda/portal-tunnel/releases/latest/download/install.sh | bash portal expose 3000
**Windows (PowerShell):**
$ProgressPreference = 'SilentlyContinue' irm https://github.com/gosuda/portal-tunnel/releases/latest/download/install.ps1 | iex portal expose 3000
Portal prints an HTTPS URL when the tunnel is ready. To get a short URL without an Ethereum address, use `--name myapp` when creating the identity. When that name is available, share `https://myapp.<relay-domain>/`, printed as `short URL` in the readiness message (`alias_url` in JSON logs). The identity-bound URL is also available; it includes the Ethereum address and supports opt-in relay caching. If the name is already taken, Portal prints only the identity-bound URL. An existing identity keeps its saved name; use a new `--identity-path` to choose a different name. Additional common usages:
# Custom name and explicit relay portal expose 3000 --name myapp --relays https://portal.example.com --discovery=false # Mount multiple local services behind one domain portal expose --name myapp \ --http-route /api=http://127.0.0.1:3001 \ --http-route /=http://127.0.0.1:5173 # Dedicated raw TCP port (Minecraft, SSH, databases) portal expose localhost:25565 --name minecraft --tcp # Prefer an IVNP overlay backhaul path portal expose 3000 --overlay
2. Use the local AI agent plugin
The repository includes two plugins for Codex, Claude Code, and Cursor: `portal-tunnel` (`portal-expose` and `portal-connect`) for publishing and reaching services, and `portal-relay` for running a relay:
# GitHub CLI gh skill install gosuda/portal-tunnel portal-tunnel/portal-expose # skills CLI npx skills add gosuda/portal-tunnel --skill portal-expose
Ask your agent: *"Expose my app on port 3000 with Portal and verify the public URL."* See [plugins/portal-tunnel/README.md](plugins/portal-tunnel/README.md) and [plugins/portal-relay/README.md](plugins/portal-relay/README.md) for full setup instructions.
3. Manage persistent tunnels with Portal Agent
When tunnels should run continuously in the background or as a system service:
portal agent run --config config.toml portal agent dashboard --config config.toml
See the [Portal Agent Guide](https://gosuda.github.io/portal-tunnel/portal-agent) for configuration syntax and OS service installation.
4. Run your own relay
Deploy an open-source relay in seconds:
git clone https://github.com/gosuda/portal-tunnel cd portal-tunnel && cp .env.example .env docker compose up
See [Deployment](https://gosuda.github.io/portal-tunnel/deployment) for DNS automation (ACME), TCP/UDP port ranges, and production policy configuration.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 20 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "portal-tunnel",
- "owner": {
- "name": "gosuda"
- },
- "plugins": [
- {
- "name": "portal-tunnel",
- "source": "./plugins/portal-tunnel"
- },
- {
- "name": "portal-relay",
- "source": "./plugins/portal-relay"
- },
- {
- "name": "portal-deploy",
- "source": "./plugins/portal-deploy"
- }
- ]
- }
README.md · README · 185 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <img src="./logo.png" alt="Portal" width="280" />
- </p>
- # Portal - Self-Hostable Relay Tunnel for Localhost
- [](https://github.com/gosuda/portal-tunnel/actions/workflows/ci.yml)
- [](https://github.com/gosuda/portal-tunnel/releases/latest)
- [](./LICENSE)
- [](https://github.com/anderspitman/awesome-tunneling)
- [English](./README.md) | [简体中文](./README.zh-CN.md)
- <p align="center"><img width="800" alt="Portal Demo" src="./portal.gif" /></p>
- <p align="center"><b>Expose local services through self-hosted or public relays.</b><br/>No port forwarding. No inbound firewall rules. No manual DNS setup. No accounts.</p>
- ## Why Portal?
- Portal is an open-source tunnel runtime and relay network for publishing services to the agentic web. It exposes local apps, APIs, tools, and agents through self-hosted or public relays, keeps routing and security policy in the local tunnel process, and eliminates the need for hosted vendor accounts or credit cards.
- - **Self-Hostable & Open Source** - Run your own relay with a single command. MIT-licensed with zero telemetry, no enterprise tiers, and no call-home.
- - **Anonymous Relay Network** - Connect to public relays or combine self-hosted and community relays into resilient multi-relay failover pools.
- - **End-to-End Tenant TLS** - For uncached HTTPS stream exposures, TLS terminates in your local tunnel process. Forwarding relays handle ciphertext; relay-held certificate keys remain part of the [trust boundary](https://gosuda.github.io/portal-tunnel/security-model#relay-trust-reduction).
- - **IVNP-backed Overlay Networking** - Bridge reverse backhauls over an independent IVNP overlay network when enhanced routing privacy is desired.
- - **Built-in MITM Detection** - The native self-probe compares TLS keying material on a sampled connection; `--ban-mitm` blocks a relay for that exposure when exporter values differ.
- - **No Accounts, No API Keys** - Authentication uses local secp256k1 cryptographic identities (`identity.json`) with SIWE challenge signing.
- - **Native x402 Payments** - Route-level micropayments using gasless Sui USDC, Casper wCSPR, or Nano XNO without traditional payment processors.
- > The **[Feature Inventory](https://gosuda.github.io/portal-tunnel/features)** lists all 20+ capabilities across CLI, Agent, SDK, and Relay, with interface support and trust boundaries.
- ## Comparison
- | | Portal | ngrok | Cloudflare Tunnel | frp |
- |---|---|---|---|---|
- | Public localhost URL | **Yes** | Yes | Yes | Yes |
- | Self-hostable | **Yes** | Enterprise only | No | Yes |
- | Open source | **MIT** | No | Client only | Apache 2.0 |
- | Custom domain | **Yes** | Paid plans | Yes | Yes |
- | End-to-end tenant TLS | **Yes (uncached exposures)** | No | No | No |
- | MITM self-probe | **Yes (TLS keying material export)** | No | No | No |
- | Multi-relay failover | **Yes** | Managed | Built-in | No |
- | Account required | **No** | Yes | Yes | No |
- | Native x402 payments | **Yes** | No | No | No |
- ## Quick Start
- ### 1. Expose a local service
- **macOS / Linux:**
- ```bash
- curl -fsSL https://github.com/gosuda/portal-tunnel/releases/latest/download/install.sh | bash
- portal expose 3000
- ```
- **Windows (PowerShell):**
- ```powershell
- $ProgressPreference = 'SilentlyContinue'
- irm https://github.com/gosuda/portal-tunnel/releases/latest/download/install.ps1 | iex
- portal expose 3000
- ```
- Portal prints an HTTPS URL when the tunnel is ready. To get a short URL without
- an Ethereum address, use `--name myapp` to select the service. When that
- name is available, share `https://myapp.<relay-domain>/`, printed as `short URL`
- in the readiness message (`alias_url` in JSON logs). The identity-bound URL is
- also available; it includes the Ethereum address and supports opt-in relay
- caching. If the name is already taken, Portal prints only the identity-bound URL.
- The identity file supplies a reusable signing key. Repeat `--name myapp` on
- later runs to select the same service, or choose another name to serve a
- different service with that key. New files do not save the name; omitting it
- selects the unnamed service. Older files retain their saved name as the default.
- See [identity names](https://gosuda.github.io/portal-tunnel/cli-reference#identity-names)
- for URL behavior. Additional common usages:
- ```bash
- # Custom name and explicit relay
- portal expose 3000 --name myapp --relays https://portal.example.com --discovery=false
- # Mount multiple local services behind one domain
- portal expose --name myapp \
- --http-route /api=http://127.0.0.1:3001 \
- --http-route /=http://127.0.0.1:5173
- # Dedicated raw TCP port (Minecraft, SSH, databases)
- portal expose localhost:25565 --name minecraft --tcp
- # Prefer an IVNP overlay backhaul path
- portal expose 3000 --overlay
- ```
- ### 2. Use the local AI agent plugin
- The repository includes two plugins for Codex, Claude Code, and Cursor: `portal-tunnel` (`portal-expose` and `portal-connect`) for publishing and reaching services, and `portal-relay` for running a relay:
- ```bash
- # GitHub CLI
- gh skill install gosuda/portal-tunnel portal-tunnel/portal-expose
- # skills CLI
- npx skills add gosuda/portal-tunnel --skill portal-expose
- ```
- Ask your agent: *"Expose my app on port 3000 with Portal and verify the public URL."* See [plugins/portal-tunnel/README.md](plugins/portal-tunnel/README.md) and [plugins/portal-relay/README.md](plugins/portal-relay/README.md) for full setup instructions.
- ### 3. Manage persistent tunnels with Portal Agent
- When tunnels should run continuously in the background or as a system service:
- ```bash
- portal agent run --config config.toml
- portal agent dashboard --config config.toml
- ```
- See the [Portal Agent Guide](https://gosuda.github.io/portal-tunnel/portal-agent) for configuration syntax and OS service installation.
- ### 4. Run your own relay
- Deploy an open-source relay in seconds:
- ```bash
- git clone https://github.com/gosuda/portal-tunnel
- cd portal-tunnel && cp .env.example .env
- docker compose up
- ```
- See [Deployment](https://gosuda.github.io/portal-tunnel/deployment) for DNS automation (ACME), TCP/UDP port ranges, and production policy configuration.
- ## How End-to-End Encryption Works
- The ordinary uncached forwarding path works as follows:
- ```text
- Browser
- -> Relay SNI router (reads ClientHello/SNI, forwards tenant ciphertext)
- -> Reverse session
- -> Portal tunnel (completes TLS handshake locally, derives session keys)
- -> Local service
- ```
- 1. **SNI Routing**: The relay accepts the incoming connection and reads only the TLS ClientHello for SNI-based lease routing.
- 2. **Raw Forwarding**: It forwards the raw encrypted stream over the reverse session without terminating TLS.
- 3. **Local Handshake**: The Portal tunnel completes the TLS handshake locally; session keys are derived on your machine.
- 4. **Keyless Signing**: For relay-hosted domains, the relay signs handshake transcripts via `/v1/sign`. The relay never receives session keys.
- 5. **Ciphertext Security**: The relay continues forwarding ciphertext without access to tenant plaintext.
- Portal minimizes relay trust; it does not yet eliminate it. A malicious relay
- with the certificate private key can still impersonate an endpoint, and the
- self-probe checks only sampled connections. See the
- [Security Model](https://gosuda.github.io/portal-tunnel/security-model#relay-trust-reduction)
- for guarantees and exceptions, or
- [Keyless TLS Explained](https://gosuda.github.io/portal-tunnel/keyless-tls)
- for the design rationale.
- ## Public Relay Registry
- Portal includes the official public relay registry by default:
- ```text
- https://raw.githubusercontent.com/gosuda/portal-tunnel/main/registry.json
- ```
- If you operate a public Portal relay, open a pull request to add your relay URL to `registry.json`.
- ## Documentation
- - **[Feature Inventory](https://gosuda.github.io/portal-tunnel/features)** - Canonical inventory of all product capabilities and interfaces.
- - **[Getting Started](https://gosuda.github.io/portal-tunnel/getting-started)** - Step-by-step setup and first exposure.
- - **[Concepts](https://gosuda.github.io/portal-tunnel/concepts)** - Relay and tunnel ownership, transport modes, and overlay networking.
- - **[Security Model](https://gosuda.github.io/portal-tunnel/security-model)** - Tenant TLS guarantees, relay signing authority, and cache exceptions.
- - **[Keyless TLS Explained](https://gosuda.github.io/portal-tunnel/keyless-tls)** - Technical article on transcript signing, MITM self-probes, and delegation.
- - **[CLI Reference](https://gosuda.github.io/portal-tunnel/cli-reference)** - Complete command-line syntax and flag guide.
- - **[Portal Agent](https://gosuda.github.io/portal-tunnel/portal-agent)** - Multi-tunnel daemon and interactive dashboard.
- - **[Self-Hosting](https://gosuda.github.io/portal-tunnel/self-hosting)** - Running and securing your own relay instances.
- - **[Configuration](https://gosuda.github.io/portal-tunnel/configuration)** - Environment variables and configuration options.
- - **[API Reference](https://gosuda.github.io/portal-tunnel/api-reference)** - Relay wire protocol and client APIs.
- - **[Maintainer Architecture](docs/maintainer/architecture.md)** - Internal Go package ownership and data flows.
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md).
- ## License
- MIT License - see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.