Portal Expose

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. 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/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 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.

Choose the Mode

Use the smallest mode that satisfies the request:

• Temporary web preview: portal expose <target>.
• Connect the app to a relay the user picked, as its website's quick start does: install Portal from the official GitHub installer if it is missing, then portal expose <target> --name <name> --relays <relay-url>, with --discovery=false when only that relay should carry the app.
• 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.
• Go app that should carry the tunnel in-process instead of running the CLI next to it: 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 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 enumerable through each participating relay's GET /api/state unless the user asked for --hide, and that relays which enable their directory page show it there too.

3. Check Portal

• Run portal version when portal is available.
• If Portal is missing, present the official GitHub installer and request approval before running it because installation writes outside the project. A relay also serves an installer at <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.
• 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 derive a DNS-label-safe name from the app and pass it explicitly, so the public URL https://<name>.<relay-host>/ is known before the tunnel starts; the relay website always emits --name for the same reason. --name applies only when the identity file is created. An existing --identity-path keeps its saved name and silently ignores the flag, so use one identity file per public name.
• 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.
• Map the app's settings onto the command the way the relay quick-start form does: a port or 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.
• The MITM self-probe runs against every relay whose tenant TLS stack exports keying material. 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; it then refuses relays that cannot export keying material instead of serving unprotected. --cache opts out of the probe entirely because it deliberately lets the relay terminate TLS, and it cannot be combined with --ban-mitm.
• Never add TCP, UDP, payment, --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.
• For a paid route, follow 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.

Before executing, show the exact public target and any important exposure consequence when it is not already obvious from the user's request.

5. Start and Observe the Tunnel

• Run a temporary portal expose in a foreground PTY or managed long-running command session. Do not hide it behind an untracked nohup process.
• For persistent mode, inspect any existing agent config and running service first. 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.
• Create or update only the selected agent config, then start it with 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.
• Do not run portal agent dashboard. It is an interactive TUI. Give the user that command in the handoff.
• Capture bounded output. Redact tokens, identity material, signed payloads, and credentials.
• HTTP tunnels are ready on a log event with field 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. 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.