/d3k

name: d3k
description: Test and debug a web app in its existing d3k browser, including local Chrome connected to a Vercel Sandbox over CDP. Use for UI checks, browser interactions, screenshots, and reproducing app issues when d3k is running.

d3k

Own the project's dev server and monitored browser through a small background runtime. No global d3k installation is needed. Evidence stays in bounded memory; browser authentication stays in the project Chrome profile.

Use `node <skill-directory>/scripts/runtime.mjs` as `runtime` below, from the **target project root**. In a development checkout the helper runs the source with Bun; installed skills use the JavaScript package through `pnpm dlx` (Node.js 24+ and pnpm required). Package acquisition runs in an isolated temporary directory so the target app’s pnpm workspace settings do not affect it; runtime commands still run against the target project. To try unreleased source from another project, set `D3K_RUNTIME_ROOT` to the dev3000 checkout. Do not use a previously published package to test unreleased changes.

Desktop MCP connection

When d3k MCP tools are available, use them directly instead of the shell runtime below. They manage a remote project without a local checkout. Call `sandbox_sessions`, then `sandbox_start` with `project: "team/project"` or `resume: "<saved-id>"`. Poll `sandbox_status` until `phase: "ready"`; startup is asynchronous. If another companion owns a saved session, report it instead of taking over or killing it.

An explicit request for a remote sandbox takes precedence over a linked local repository. Use `project` and the requested `branch` to create a fresh remote checkout. Reuse with `resume` or `attach` only when requested by the user. If creation fails, report its actual error; do not assume the repository is private, attach to an old checkout, discard the requested branch, or fall back to editing locally.

For a phone user or an explicit phone-preview request, use `sandbox_start` with `browser: "link"`, then present the ready `sandbox_status.preview.url` as a clickable link and its `expiresAt`. Never give the phone a `.localhost` URL. Companion Chrome runs headlessly for agent testing; it cannot control the phone's browser. The link grants session app access, so share it only in the user's chat and keep it out of PRs/public logs. It expires with the session and is regenerated on resume; use `browser: "link"` again when resuming. Local stdio carries no phone User-Agent: use explicit user/client context, not the emulated viewport. The macOS companion and access to its local MCP server are still required; this does not provide phone-only ChatGPT connectivity. App sign-in may require allowing the preview origin's exact callback URL with the auth provider.

Use `sandbox_exec`, `sandbox_read_file`, and `sandbox_write_file` for all project files and commands remotely. Read remote AGENTS.md before editing. Use `sandbox_runtime` with `args: ["status"]` and cursor-based events for evidence. Use `sandbox_browser` with `args: ["snapshot", "-i"]` and other agent-browser interaction arguments for the existing local Chrome; no CDP discovery or separate browser is needed. `sandbox_github` publishes Git objects and PRs through local repository-scoped GitHub authentication. Keep credentials out of remote commands. Do not clone or save project code/env files locally.

If the dev runtime stops or the app returns 502, use `sandbox_recover` with `action: "start"`, then poll `action: "status"` until recovered or failed. Recovery keeps the agent, local Chrome and remote files; it does not clone, reinstall, replay commands, renew Gateway keys or extend compute lifetime. Reread runtime status and reproduce afterward; old in-memory evidence is lost on restart.

Keep the session running during user testing. `sandbox_stop` returns stopping; poll until stopped. Stopping or disconnecting the MCP server closes Chrome and d3k-owned compute, preserves remote files, and leaves a resumable session. One active sandbox per server. No terminal harness or Gateway key is created; the desktop client supplies the model. The desktop conversation may retain source returned by tools.

For one-time desktop setup, use `d3k mcp --print-config`. Configure its local stdio command/args/environment in ChatGPT Desktop's MCP settings or merge the generated entry into Claude Desktop's `mcpServers` configuration, preserving other servers. The command uses absolute paths and a GUI-compatible PATH; regenerate it after replacing the installation. Local Vercel login and canonical Portless must be ready before starting a session. The CLI's `mcp` entry point also supplies these instructions when the standalone skill isn't installed.

Prepare

For an already connected d3k session, use its existing runtime and browser. The dev server may be running remotely in the sandbox even when the harness UI is local. Inspect status through the connected session before inferring that a server needs starting; do not start a local server to verify the remote app. After a user-visible UI edit, verify the changed page in the paired browser and read the relevant events before reporting completion. Report the actual command/tool error if verification is blocked.

1. Run `runtime portless status`. Canonical HTTPS must be ready (`canonical: true`, `serviceInstalled: true`, `setupRequired: false`) before starting the app or browser. If needed run `runtime portless setup`, wait for the one-time administrator authorization, then check again. Stop if setup is unavailable; never silently substitute direct localhost. 2. Run `runtime status`. Reuse a ready runtime for this project. If it is starting, wait for readiness. Do not start another dev server. 3. Start `runtime start` in a retained background tool session. Keep its process handle. The runtime detects the package manager and `dev` script; use `--command '<dev command>'` when needed. Poll `runtime status` until `ready: true` and `