Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
DevOps & cloud

portal-expose

Expose, preview, protect with x402 payments, or keep a local web app, static site, HTTP route set, or explicitly requested TCP/UDP service reachable through Portal, then verify the public endpoint and report its lifecycle. Use when the user asks to deploy, publish, share, tunnel, expose, create a public preview, add a paid route, or configure x402 for a local app with Portal. Do not use for deploying a Portal relay, generic cloud hosting, or publishing this plugin.

gosuda · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add gosuda/portal-tunnel --skill portal-expose

About this skill


name: portal-expose description: Expose, preview, protect with x402 payments, or keep a local web app, static site, HTTP route set, or explicitly requested TCP/UDP service reachable through Portal, then verify the public endpoint and report its lifecycle. Use when the user asks to deploy, publish, share, tunnel, expose, create a public preview, add a paid route, or configure x402 for a local app with Portal. Do not use for deploying a Portal relay, generic cloud hosting, or publishing this plugin. license: MIT

Expose an App with Portal

Portal publishes a service that is already running on the user's machine. It does not build the app or move it to a cloud host. Treat a successful tunnel as dependent on both the local app and the Portal process or agent remaining available.

Run the workflow in order. Open a reference only when that branch is taken: references/x402.md for a paid route, references/safety-and-verification.md for an authenticated, sensitive/high-risk, or non-HTTP service, references/game-hosting.md for a game server, references/portal-cli.md when choosing persistent-agent configuration. Use the installed portal CLI for flags.

Choose the Mode

Use the smallest mode that satisfies the request:

  • Temporary web preview: portal expose <target>.
  • Trusted static directory or HTML entry: portal expose --serve <path>.
  • Multiple local HTTP services under one URL: repeat --http-route.
  • Paid HTTP path: routed HTTP with an explicit x402 payment contract; never enable payment implicitly.
  • Durable tunnel that should survive terminal or login restarts: an explicit portal agent config and managed service.
  • Session-owned durable tunnel without an OS service: portal agent run --foreground.
  • Game server (Minecraft, Terraria, Palworld, or any dedicated game server): always start from references/game-hosting.md — raw TCP/UDP transport has different prerequisites and verification than HTTP.

Default to a temporary preview when the user says only "share", "preview", or "deploy locally". Do not install an OS service unless the user asks for a persistent, managed, or restart-surviving tunnel and accepts that portal agent run without --foreground installs a per-user launchd or systemd unit.

Workflow

1. Inspect the Project

  • Read the applicable repository instructions before running or changing anything.
  • Determine the app directory, start command, expected protocol, loopback target, and a meaningful health path.
  • Prefer declared scripts and documented ports over guessing from process lists.
  • Do not expose a port merely because it is listening. Tie it to the requested app.
  • If the project is already running, preserve its process. If it is not running and deployment was requested, start it with the project's normal command and retain the terminal/session handle.

Ask one concise question only when the target, desired lifetime, or transport cannot be discovered safely. An explicit request to deploy, publish, expose, tunnel, or share authorizes creating the public tunnel for the named app; it does not authorize exposing adjacent services.

For x402, do not guess the protected path, payment methods, amount, network, recipient, or network-specific asset. Collect any missing consequential value before building the command or config. Treat an omitted method list as charging every method on the route and confirm that scope when it was not explicit.

2. Verify the Local Service

  • Wait for the app's real readiness signal, not only for the process to exist.
  • Make a bounded local request to the selected target. For HTTP, record the URL and status. For TCP/UDP, use a protocol-appropriate check that does not mutate application data.
  • Stop before opening a tunnel if the local health check fails.
  • Warn and require explicit direction before exposing databases, container daemons, debug consoles, unauthenticated admin panels, or services containing sensitive data.
  • Before opening the tunnel, say that the public hostname is listed on participating relays and visible via portal list unless the user asked for --hide.

3. Check Portal

  • Run portal version when portal is available.
  • If Portal is missing, present the official install method and request approval before running it because installation writes outside the project. Never execute an installer from an unknown relay or third-party URL.
  • Do not assume a hard-coded latest release or stale flags. Use the installed Portal version as the compatibility baseline.

4. Build the Command or Agent Config

  • Use loopback targets such as 127.0.0.1:<port> unless the project explicitly needs another address.
  • Use the user's requested name. Otherwise omit --name for a temporary preview or derive a stable DNS-label-safe name for a persistent tunnel.
  • For portal expose, always pass an absolute --identity-path outside the repository. The CLI default is identity.json in the process working directory and that file contains private key material. For portal agent, omit identity_path so the agent stores identity under its state directory; if you set the field, use an absolute path outside the repository.
  • Never print or commit identity JSON, control tokens, facilitator tokens, or wallet secrets.
  • With a user-selected relay on portal expose, pass --relays <https-url> --discovery=false. In persistent mode those flags are not accepted on portal agent run; put relays = ["https://..."] and discovery = false on the [[tunnels]] entry instead.
  • The MITM self-probe always runs. Without --ban-mitm / ban_mitm = true, a suspected TLS termination is only logged and the tunnel keeps serving. Do not claim the default path blocks a relay. Add --ban-mitm only when the user wants fail-closed handling. There is no flag that disables the probe.
  • Never add TCP, UDP, multi-hop, payment, or public metadata flags that the user did not request. --hide is the exception for listing: mentio
Read the complete source ↗