agentic-runtime-preview

# 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: ```text 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: ```bash agentic-runtime-preview register --port 5173 --label "Vite dev server" --protocol http --ttl-seconds 7200 --json ``` List registered preview ports: ```bash agentic-runtime-preview list --json ``` Delete a preview port: ```bash 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: ```bash 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: ```text http://127.0.0.1:18080 ``` Override only that local API base URL with: ```text 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.