Skip to content
Back to search

portal-tunnel

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gosuda--portal-tunnel/badge.svg)](/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

i

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.

  1. {
  2. "name": "portal-tunnel",
  3. "owner": {
  4. "name": "gosuda"
  5. },
  6. "plugins": [
  7. {
  8. "name": "portal-tunnel",
  9. "source": "./plugins/portal-tunnel"
  10. },
  11. {
  12. "name": "portal-relay",
  13. "source": "./plugins/portal-relay"
  14. },
  15. {
  16. "name": "portal-deploy",
  17. "source": "./plugins/portal-deploy"
  18. }
  19. ]
  20. }
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.

  1. <p align="center">
  2. <img src="./logo.png" alt="Portal" width="280" />
  3. </p>
  4. # Portal - Self-Hostable Relay Tunnel for Localhost
  5. [![CI](https://github.com/gosuda/portal-tunnel/actions/workflows/ci.yml/badge.svg)](https://github.com/gosuda/portal-tunnel/actions/workflows/ci.yml)
  6. [![GitHub Release](https://img.shields.io/github/v/release/gosuda/portal-tunnel)](https://github.com/gosuda/portal-tunnel/releases/latest)
  7. [![License](https://img.shields.io/github/license/gosuda/portal-tunnel)](./LICENSE)
  8. [![awesome-tunneling](https://img.shields.io/badge/awesome--tunneling-listed-blue)](https://github.com/anderspitman/awesome-tunneling)
  9. [English](./README.md) | [简体中文](./README.zh-CN.md)
  10. <p align="center"><img width="800" alt="Portal Demo" src="./portal.gif" /></p>
  11. <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>
  12. ## Why Portal?
  13. 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.
  14. - **Self-Hostable & Open Source** - Run your own relay with a single command. MIT-licensed with zero telemetry, no enterprise tiers, and no call-home.
  15. - **Anonymous Relay Network** - Connect to public relays or combine self-hosted and community relays into resilient multi-relay failover pools.
  16. - **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).
  17. - **IVNP-backed Overlay Networking** - Bridge reverse backhauls over an independent IVNP overlay network when enhanced routing privacy is desired.
  18. - **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.
  19. - **No Accounts, No API Keys** - Authentication uses local secp256k1 cryptographic identities (`identity.json`) with SIWE challenge signing.
  20. - **Native x402 Payments** - Route-level micropayments using gasless Sui USDC, Casper wCSPR, or Nano XNO without traditional payment processors.
  21. > 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.
  22. ## Comparison
  23. | | Portal | ngrok | Cloudflare Tunnel | frp |
  24. |---|---|---|---|---|
  25. | Public localhost URL | **Yes** | Yes | Yes | Yes |
  26. | Self-hostable | **Yes** | Enterprise only | No | Yes |
  27. | Open source | **MIT** | No | Client only | Apache 2.0 |
  28. | Custom domain | **Yes** | Paid plans | Yes | Yes |
  29. | End-to-end tenant TLS | **Yes (uncached exposures)** | No | No | No |
  30. | MITM self-probe | **Yes (TLS keying material export)** | No | No | No |
  31. | Multi-relay failover | **Yes** | Managed | Built-in | No |
  32. | Account required | **No** | Yes | Yes | No |
  33. | Native x402 payments | **Yes** | No | No | No |
  34. ## Quick Start
  35. ### 1. Expose a local service
  36. **macOS / Linux:**
  37. ```bash
  38. curl -fsSL https://github.com/gosuda/portal-tunnel/releases/latest/download/install.sh | bash
  39. portal expose 3000
  40. ```
  41. **Windows (PowerShell):**
  42. ```powershell
  43. $ProgressPreference = 'SilentlyContinue'
  44. irm https://github.com/gosuda/portal-tunnel/releases/latest/download/install.ps1 | iex
  45. portal expose 3000
  46. ```
  47. Portal prints an HTTPS URL when the tunnel is ready. To get a short URL without
  48. an Ethereum address, use `--name myapp` to select the service. When that
  49. name is available, share `https://myapp.<relay-domain>/`, printed as `short URL`
  50. in the readiness message (`alias_url` in JSON logs). The identity-bound URL is
  51. also available; it includes the Ethereum address and supports opt-in relay
  52. caching. If the name is already taken, Portal prints only the identity-bound URL.
  53. The identity file supplies a reusable signing key. Repeat `--name myapp` on
  54. later runs to select the same service, or choose another name to serve a
  55. different service with that key. New files do not save the name; omitting it
  56. selects the unnamed service. Older files retain their saved name as the default.
  57. See [identity names](https://gosuda.github.io/portal-tunnel/cli-reference#identity-names)
  58. for URL behavior. Additional common usages:
  59. ```bash
  60. # Custom name and explicit relay
  61. portal expose 3000 --name myapp --relays https://portal.example.com --discovery=false
  62. # Mount multiple local services behind one domain
  63. portal expose --name myapp \
  64. --http-route /api=http://127.0.0.1:3001 \
  65. --http-route /=http://127.0.0.1:5173
  66. # Dedicated raw TCP port (Minecraft, SSH, databases)
  67. portal expose localhost:25565 --name minecraft --tcp
  68. # Prefer an IVNP overlay backhaul path
  69. portal expose 3000 --overlay
  70. ```
  71. ### 2. Use the local AI agent plugin
  72. 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:
  73. ```bash
  74. # GitHub CLI
  75. gh skill install gosuda/portal-tunnel portal-tunnel/portal-expose
  76. # skills CLI
  77. npx skills add gosuda/portal-tunnel --skill portal-expose
  78. ```
  79. 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.
  80. ### 3. Manage persistent tunnels with Portal Agent
  81. When tunnels should run continuously in the background or as a system service:
  82. ```bash
  83. portal agent run --config config.toml
  84. portal agent dashboard --config config.toml
  85. ```
  86. See the [Portal Agent Guide](https://gosuda.github.io/portal-tunnel/portal-agent) for configuration syntax and OS service installation.
  87. ### 4. Run your own relay
  88. Deploy an open-source relay in seconds:
  89. ```bash
  90. git clone https://github.com/gosuda/portal-tunnel
  91. cd portal-tunnel && cp .env.example .env
  92. docker compose up
  93. ```
  94. See [Deployment](https://gosuda.github.io/portal-tunnel/deployment) for DNS automation (ACME), TCP/UDP port ranges, and production policy configuration.
  95. ## How End-to-End Encryption Works
  96. The ordinary uncached forwarding path works as follows:
  97. ```text
  98. Browser
  99. -> Relay SNI router (reads ClientHello/SNI, forwards tenant ciphertext)
  100. -> Reverse session
  101. -> Portal tunnel (completes TLS handshake locally, derives session keys)
  102. -> Local service
  103. ```
  104. 1. **SNI Routing**: The relay accepts the incoming connection and reads only the TLS ClientHello for SNI-based lease routing.
  105. 2. **Raw Forwarding**: It forwards the raw encrypted stream over the reverse session without terminating TLS.
  106. 3. **Local Handshake**: The Portal tunnel completes the TLS handshake locally; session keys are derived on your machine.
  107. 4. **Keyless Signing**: For relay-hosted domains, the relay signs handshake transcripts via `/v1/sign`. The relay never receives session keys.
  108. 5. **Ciphertext Security**: The relay continues forwarding ciphertext without access to tenant plaintext.
  109. Portal minimizes relay trust; it does not yet eliminate it. A malicious relay
  110. with the certificate private key can still impersonate an endpoint, and the
  111. self-probe checks only sampled connections. See the
  112. [Security Model](https://gosuda.github.io/portal-tunnel/security-model#relay-trust-reduction)
  113. for guarantees and exceptions, or
  114. [Keyless TLS Explained](https://gosuda.github.io/portal-tunnel/keyless-tls)
  115. for the design rationale.
  116. ## Public Relay Registry
  117. Portal includes the official public relay registry by default:
  118. ```text
  119. https://raw.githubusercontent.com/gosuda/portal-tunnel/main/registry.json
  120. ```
  121. If you operate a public Portal relay, open a pull request to add your relay URL to `registry.json`.
  122. ## Documentation
  123. - **[Feature Inventory](https://gosuda.github.io/portal-tunnel/features)** - Canonical inventory of all product capabilities and interfaces.
  124. - **[Getting Started](https://gosuda.github.io/portal-tunnel/getting-started)** - Step-by-step setup and first exposure.
  125. - **[Concepts](https://gosuda.github.io/portal-tunnel/concepts)** - Relay and tunnel ownership, transport modes, and overlay networking.
  126. - **[Security Model](https://gosuda.github.io/portal-tunnel/security-model)** - Tenant TLS guarantees, relay signing authority, and cache exceptions.
  127. - **[Keyless TLS Explained](https://gosuda.github.io/portal-tunnel/keyless-tls)** - Technical article on transcript signing, MITM self-probes, and delegation.
  128. - **[CLI Reference](https://gosuda.github.io/portal-tunnel/cli-reference)** - Complete command-line syntax and flag guide.
  129. - **[Portal Agent](https://gosuda.github.io/portal-tunnel/portal-agent)** - Multi-tunnel daemon and interactive dashboard.
  130. - **[Self-Hosting](https://gosuda.github.io/portal-tunnel/self-hosting)** - Running and securing your own relay instances.
  131. - **[Configuration](https://gosuda.github.io/portal-tunnel/configuration)** - Environment variables and configuration options.
  132. - **[API Reference](https://gosuda.github.io/portal-tunnel/api-reference)** - Relay wire protocol and client APIs.
  133. - **[Maintainer Architecture](docs/maintainer/architecture.md)** - Internal Go package ownership and data flows.
  134. ## Contributing
  135. See [CONTRIBUTING.md](CONTRIBUTING.md).
  136. ## License
  137. MIT License - see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.