agentic-runtime-preview

name	agentic-runtime-preview
description	Use when you start a local HTTP development server in an agent-runtime sandbox and need to return an externally accessible preview URL to the user.

Agentic Runtime Preview

Use this skill when a local HTTP development server in an agent-runtime sandbox needs an externally accessible preview URL. For ordinary servers, register after the server starts. For PUBLIC_BASE_URL-first servers, register the chosen port before startup so the runtime can return the public URL that the server must use.

Required instruction:

When you start a local HTTP development server for the user to view, register its port with agentic-runtime-preview and return only the previewUrl. If the server must know its public base URL before startup, register the chosen port first, set the selected public base URL environment variable to the returned previewUrl, then start or restart the server. Do not tell the user to open localhost URLs.

Commands

Register a listening HTTP development server:

agentic-runtime-preview register --port 5173 --label "Vite dev server" --protocol http --ttl-seconds 7200 --json

List registered preview ports:

agentic-runtime-preview list --json

Delete a preview port:

agentic-runtime-preview delete --port 5173 --json

Workflow

Ordinary dev server

Use this when the application does not need to know its public preview URL before it starts.

1. Start the local HTTP development server and verify the port number from the command or server output.
2. Register that port with agentic-runtime-preview register.
3. Parse the returned JSON.
4. Return only the previewUrl value to the user as the browser entrypoint.

PUBLIC_BASE_URL-first dev server

Use this when the application must know its public base URL before startup, for example for callbacks, absolute asset URLs, WebSocket origins, or framework-specific public URL configuration. This pre-start path exists when you must register the port before starting the dev server to obtain the runtime-provided public URL.

1. Choose the HTTP port the dev server will use.
2. Register the port before starting the dev server:

agentic-runtime-preview register --port 5173 --label "Vite dev server" --protocol http --ttl-seconds 7200 --json

3. Parse the returned JSON and keep the previewUrl.
4. Set the selected project-appropriate public base URL environment variable to the returned previewUrl, such as PUBLIC_BASE_URL, VITE_PUBLIC_BASE_URL, APP_PUBLIC_BASE_URL, or an equivalent project-specific variable, before starting or restarting the dev server.
5. Return the previewUrl to the user. If the runtime response status is pending, starting, or unreachable, keep the URL and mention briefly that the server is still starting.

Only use the previewUrl returned by the runtime API. Do not construct preview hosts, subdomains, previewRuntimeId, frp rules, or public URLs yourself.

Configuration

The helper calls the local writable runtime preview API. The default API base URL is:

http://127.0.0.1:18080

Override only that local API base URL with:

AGENTIC_RUNTIME_PREVIEW_API_BASE_URL

This variable is not a public preview domain. Do not read Helm values, Control Plane config, platform config, DNS zones, app-seed config, or any platform-owned preview domain setting.

Safety

Register only HTTP development server ports started for the current user task. Do not register database, Redis, message broker, runtime HTTP, frpc admin, local preview control, internal platform API, non-HTTP, or unknown TCP service ports.

Do not infer a preview port only from assistant prose. Use the actual server command, server output, or explicit user-provided port.

If registration fails, report the runtime error code and short message. Do not expose frpc credentials, Kubernetes Secret paths, host paths, or raw internal admin URLs.

Do not add browser, generated-app, helper, or local API registration credentials. The writable preview API is scoped by the agent-runtime loopback listener and sandbox trust boundary.