- name
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gosuda/portal-tunnel --skill portal-expose -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gosuda/portal-tunnel --skill portal-expose -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gosuda/portal-tunnel --skill portal-expose -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gosuda/portal-tunnel --skill portal-expose -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/gosuda/portal-tunnel/tree/HEAD/plugins/portal-tunnel/skills/portal-exposeFrom the publisher
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. This is the app side of Portal: every relay website offers the same three steps (paste what to share, run one install-and-expose command built from the app settings, open the public URL), and this skill performs those steps for the app with verification around them. Any other program that reaches the published URL needs nothing from Portal.
Run the workflow in order. Open a reference only when that branch is taken: references/x402.md for a paid route, references/application-auth.md when only chosen people may open the URL (a credential link, wallet, OIDC, SAML, or email link sign-in), references/safety-and-verification.md for an authenticated, sensitive/high-risk, or non-HTTP service, references/game-hosting.md for a game server, references/agent-backends.md for a web UI or API that controls coding agents or a shell (herdr web clients such as Ovis, agent dashboards, browser terminals), references/webhook-endpoints.md when the URL will be registered with another service that calls it (a Discord bot or Activity, a webhook, or an OAuth redirect), references/portal-cli.md when choosing persistent-agent configuration or checking a flag, references/sdk-embed.md only for a Go app that should run the tunnel inside its own process. Use the installed portal CLI for flags.
Use the smallest mode that satisfies the request:
portal expose <target>.portal expose <target> --name <name> --relays <relay-url>, with --discovery=false when only that relay should carry the app.portal expose --serve <path>.--http-route.--auth credential, --auth siwe, --auth oidc, --auth saml, or --auth email to the same command, as references/application-auth.md describes. It needs an allowlist for OIDC, SAML, and email and cannot be combined with --tcp, --udp, or --cache.portal agent config and managed service.portal agent run --foreground.references/agent-backends.md — it gives a shell to whoever reaches it, so it needs the app's own token, routed HTTP, a hidden address, and an explicit risk approval.references/webhook-endpoints.md — it needs a stable name and identity, and it is registered only after the endpoint verifies.references/game-hosting.md — raw TCP/UDP transport has different prerequisites and verification than HTTP.references/sdk-embed.md. The CLI stays the default even for Go; embedding is for users who ask for it.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 the OS service that portal agent run without --foreground installs. Its scope depends on who runs it: a normal user gets a launchd LaunchAgent or a systemd user unit, root gets a LaunchDaemon or a unit in /etc/systemd/system, and Windows gets a service that runs as LocalSystem. Name that scope when you ask for approval.
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.
references/application-auth.md) so that only chosen people can reach it, instead of exposing the app open; do not enable it unasked.GET /api/state unless the user asked for --hide, and that relays which enable their directory page show it there too.portal version when portal is available.<relay>/api/install.sh (install.ps1 on Windows), but the relay then supplies the script, the binary, and the checksum together, so nothing in that download is verified independently of the relay. Use it only when the user explicitly prefers it, and before running the installed binary compare its SHA-256 with the checksums.txt or .sha256 asset of the matching GitHub release, fetched from github.com rather than from the relay. Never run an installer from a relay the user did not choose or from a third-party URL.127.0.0.1:<port> unless the project explicitly needs another address.https://<name>.<relay-host>/; the relay website always emits --name for the same reason. The short URL is not known before the tunnel starts: the relay grants it only when no other identity owns the name. Hand off alias_url when the relay grants it and public_url otherwise, as step 7 says. An explicit --name selects the service without rewriting its identity file. Omitting it uses a legacy saved name or an unnamed service; different explicit service names may share a signing key and have independent leases and targets.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.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.host:port is the positional target; an http(s):// URL contributes its host and port; a directory or HTML file becomes --serve <path>; a thumbnail URL, description, tags, or owner that the app or user defines go to --thumbnail, --description, --tags, --owner, all of which are public metadata; a datagram service adds --udp, with --udp-addr when the UDP port differs from the target.--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; it then refuses relays that cannot export keying material instead of serving unprotected. opts out of the probe entirely because it deliberately lets the relay terminate TLS, and it cannot be combined with .Before executing, show the exact public target and any important exposure consequence when it is not already obvious from the user's request.
portal expose in a foreground PTY or managed long-running command session. Do not hide it behind an untracked nohup process.run, restart, and stop are service-wide: they affect every [[tunnels]] entry that the selected service owns. Reuse and merge the existing config when the same agent should keep other tunnels. An isolated second agent needs its own config, service_name, state_dir, and loopback control_addr. Changing only service_name still shares the default state directory and 127.0.0.1:4018. Do not stop or replace an agent that already owns unrelated tunnels.portal agent run --config <path> after the user accepts OS-service installation (portal agent run requires the file to exist; it never creates one), or portal agent run --foreground --config <path> when the current session should own the process. --foreground opens the interactive dashboard when stdin and stdout are TTYs. Run that command in a non-TTY managed session so logs stay capturable and the TUI does not start.portal agent dashboard. It is an interactive TUI. Give the user that command in the handoff.public_url. The message still starts with service ready at. Relay https:// values in listener_relays / added_relays are not ready. Raw TCP/UDP tunnels log raw transport endpoints allocated with tcp_addr and/or udp_addr instead. waiting for relay approval means the relay is in manual mode and an admin must approve the tunnel, which then needs no restart. refused by relay means an admin denied or banned it. Report either one to the user and do not call the tunnel ready. Do not wait for an HTTPS URL on a raw transport. A later line starting relay no longer active for retracts a URL; re-verify before handoff if you see one.GET <relay>/api/state lists the hostname with ready > 0 once the tunnel can serve; ready at zero means registered but not yet connected.401 or 403; explain that as reachable but protected. A tunnel started with --auth answers an unauthenticated GET or HEAD with 303 to /_portal/auth/login; check it the way references/application-auth.md describes and never sign in as the user. Treat unexpected 5xx, TLS errors, or a Portal error page as a failed deployment.402 Payment Required plus a payment-requirements header. Compare the returned network, asset, recipient, amount, and resource with the requested policy. Verify the method scope by requesting an intentionally unprotected method when one exists. Never spend funds merely to verify configuration.tcp_addr/udp_addr without mutating application data. A successful local port open is not enough.Report:
alias_url (short URL without an Ethereum address) and verify that exact URL. Fall back to public_url when no alias is granted. Keep the identity-bound public_url as an alternative for identity-pinned origins or opt-in relay caching. Never construct an alias by removing the address suffix, and do not reuse an alias after readiness is lost or the relay is deselected.--hide.--ban-mitm.references/application-auth.md describes), how to remove someone (never by emptying the allowlist, which lets everyone in), and the exact restart command that applies a changed list.402 challenge was verified. State explicitly when settlement was not tested.Do not call the result permanent when the local machine, app process, or foreground tunnel must remain running.
If Portal-specific friction materially affected the task, report one sanitized sentence (command, expected versus actual). Do not initiate GitHub feedback handling, write feedback files, or query extra relays unless the user explicitly requests that follow-up.
Use this variant only when the user asks to expose through a relay running on this machine. The relay must already be running; the client never starts one. Do not consult or fall back to the public registry in this mode.
portal expose <loopback-target> --name <name> --identity-path <absolute-path-outside-repo> --relays https://127.0.0.1:<sni-port> --discovery=false. When port 443 is unavailable, start the same-tree relay with relay-server --portal-url https://127.0.0.1:<port>; SNI_PORT follows the PORTAL_URL port, so pass --sni-port only when the bind port differs from the public one. The SNI router is the relay's single ingress: it serves the root host's Admin/API handler in-process.service ready at carrying public_url. Listener or added-relay https:// URLs in the same output describe relay listeners, not tenant readiness.alias_url when granted, otherwise public_url) with one bounded request. *.localhost often resolves to ::1 first, so use curl -sk --ipv4 --connect-timeout 5 --max-time 15 -o /dev/null -w '%{http_code}' <public-url> and accept the app's real status (401 or 403 means reachable and protected).service ready at line within a bounded wait. Do not substitute registry relays or start extra relays to unblock the run.402 challenge: do not describe it as protected or hand it off as ready. Stop only the tunnel created by this workflow, preserve bounded diagnostics, and report the policy mismatch.--ban-mitm: report the warning and offer --ban-mitm; do not claim the relay was blocked. A self-probe timed out or self-probe failed line is not a detection; report passthrough as unverified.--name had no effect: the identity file already existed and supplied its saved name. Point --identity-path at a new file for a new name.Expose, preview, protect with x402 payments or sign-in, or keep a local web app, static site, HTTP route set, or explicitly requested TCP/UDP service reachable through Portal, then verify the public e
---name: portal-exposedescription: Expose, preview, protect with x402 payments or sign-in, or keep a local web app, static site, HTTP route set…---# plugins/portal-tunnel/skills/portal-expose/SKILL.mdOverview
Expose, preview, protect with x402 payments or sign-in, 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. This is the app side of Portal, the same flow as the quick-start form on a relay website (install, run one portal expose command built from the app settings, open the public URL). Use when the user asks to deploy, publish, share, tunnel, expose, or connect a local app to Portal or to a specific relay, create a public preview, add a paid route, configure x402, limit who can open the URL with a login, needs an HTTPS URL on a phone or another device because a browser feature such as microphone, camera, geolocation, or PWA install refuses to work over a LAN http address, or wants a Go app to embed the Portal SDK. Do not use for deploying a Portal relay, generic cloud hosting, publishing this plugin, or reaching a service that someone else already published (portal-connect).
FAQ
Download plugins/portal-tunnel/skills/portal-expose/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/gosuda/portal-tunnel.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
--cache--ban-mitmportal expose only as AUTH_OIDC_CLIENT_SECRET, AUTH_SMTP_PASSWORD, and AUTH_IDENTITY_PROOF in the environment, as references/application-auth.md describes.--auth, --auth-allow, --auth-email-list, --auth-oidc-*, --auth-saml-*, --auth-smtp-*), --cache, --cache-ttl, or --overlay flags that the user did not request; --cache hands the relay the static files and browser TLS termination. Public metadata flags are fine when their values come from the app's own settings or from the user; do not invent them. --hide is the exception for listing: mention the default public listing, then add --hide or hide = true only when the user wants the tunnel unlisted.references/x402.md. Keep payment policy on the smallest requested path, use an explicit network, and never place wallet or facilitator secrets in a command, log, committed file, or final response.