# Agentic Runtime Preview

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

- Skill: `dolphinai2026/agentic-runtime-preview` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dolphinai2026/agentic-runtime-preview`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dolphinai2026/agentic-runtime-preview/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dolphinai2026 (https://skillmd.com/u/dolphinai2026)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dolphinai2026/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.