What Browser Providers Does k-skill Support? A Complete Guide to the Browser Runtime

k-skill supports four browser providers—auto, browseros, aside, and chrome-cdp—configured via the KSKILL_BROWSER_PROVIDER environment variable or options.provider argument in the k-skill-browser-runtime package.

The NomaDamas/k-skill repository implements browser automation through a dedicated runtime package that abstracts CDP (Chrome DevTools Protocol) connections and CLI-based browser interactions. Understanding these browser providers is essential for running skills locally, debugging automation flows, or deploying to specific environments where GUI browsers may not be available.

The Four Browser Providers in k-skill

The provider constants are defined in packages/k-skill-browser-runtime/src/provider.js. Each provider represents a distinct strategy for connecting to a browser instance, ranging from automatic platform detection to direct CDP attachment.

auto

The auto provider selects the best available provider for the current platform. According to the source code in provider.js, the selection order is platform-specific:

• macOS: Aside → BrowserOS → Chrome-CDP
• Other platforms: BrowserOS → Aside → Chrome-CDP

This ordering is encoded in the DARWIN_AUTO_ORDER and AUTO_ORDER constants (lines 18–20), with the platform-specific resolution handled by resolveAutoOrder (lines 21–23). When the KSKILL_BROWSER_PROVIDER environment variable is unset, the system defaults to auto via the normalizeProvider function (lines 26–27).

browseros

The browseros provider connects to a user-launched BrowserOS GUI session via its CDP endpoint. By default, it attempts to connect to http://127.0.0.1:9100. This provider is ideal when running skills against a dedicated BrowserOS instance that exposes a private debugging port.

aside

The aside provider utilizes the Aside Browser REPL (aside), a CLI-only front-end that does not require private CDP ports or GUI sessions. This is the preferred provider for headless environments or CI/CD pipelines where running a full browser GUI is impractical.

chrome-cdp

The chrome-cdp provider attaches directly to an existing Chrome or Chromium instance via its CDP endpoint, defaulting to http://127.0.0.1:9222. This provider requires launching Chrome with the --remote-debugging-port flag beforehand and offers the most direct control over browser state.

How Provider Selection Works

Provider resolution follows a strict hierarchy implemented in normalizeProvider. The system first checks the options.provider argument passed to the connect() function, then falls back to the KSKILL_BROWSER_PROVIDER environment variable, and finally defaults to auto if neither is specified.

The auto-selection logic uses resolveAutoOrder to determine the priority array based on process.platform. On macOS (darwin), Aside is prioritized to leverage native integration, while other platforms prioritize BrowserOS for broader compatibility.

Configuration Examples

The following examples demonstrate how to invoke each provider using the k-skill-browser-runtime package:

Automatic Provider Selection

// Let the runtime pick the best provider (auto)
const { connect } = require("k-skill-browser-runtime");

connect()
  .then(({ provider, browser }) => {
    console.log(`Connected via ${provider}`);
    // Use browser (CDP or Aside API) …
  })
  .catch(console.error);

Force Chrome-CDP via Environment Variable

// Force the Chrome-CDP provider
process.env.KSKILL_BROWSER_PROVIDER = "chrome-cdp";
const { connect } = require("k-skill-browser-runtime");

connect()
  .then(({ provider, cdpUrl }) => {
    console.log(`Using ${provider} at ${cdpUrl}`);
    // …interact with Chrome via CDP
  });

Explicit Aside Provider via Options

// Explicitly request the Aside provider via options
const { connect } = require("k-skill-browser-runtime");

connect({ provider: "aside" })
  .then(({ provider, browser }) => {
    console.log(`Attached to ${provider}`);
    // …use the Aside REPL API
  });

Summary

• Four providers: k-skill supports auto, browseros, aside, and chrome-cdp through the k-skill-browser-runtime package.
• Configuration: Set via KSKILL_BROWSER_PROVIDER environment variable or options.provider argument in connect().
• Platform differences: The auto provider prioritizes Aside on macOS and BrowserOS on Linux/Windows, as defined in provider.js lines 18–23.
• Source location: Provider logic resides in packages/k-skill-browser-runtime/src/provider.js, with documentation available in docs/browser-runtime.md.

Frequently Asked Questions

How do I set the browser provider in k-skill?

You can set the browser provider by assigning the provider name to the KSKILL_BROWSER_PROVIDER environment variable before requiring the runtime, or by passing a provider property in the options object to the connect() function. The normalizeProvider function in provider.js handles this resolution, defaulting to auto when neither is specified.

What is the difference between Aside and BrowserOS providers?

The Aside provider uses a CLI-based REPL interface that does not require CDP ports or GUI sessions, making it suitable for headless environments. The BrowserOS provider connects to a full GUI browser instance via CDP at http://127.0.0.1:9100, requiring a manually launched BrowserOS session with an exposed debugging port.

Why does the auto provider order differ on macOS?

On macOS (darwin), the DARWIN_AUTO_ORDER constant places Aside first to leverage native macOS integration capabilities, followed by BrowserOS and Chrome-CDP. On other platforms, AUTO_ORDER prioritizes BrowserOS first for broader Linux/Windows compatibility, then falls back to Aside and Chrome-CDP. This platform-specific ordering is resolved by the resolveAutoOrder function at lines 21–23 of provider.js.

Where is the provider logic implemented in the k-skill source code?

The provider definitions, selection logic, and connection handlers are implemented in packages/k-skill-browser-runtime/src/provider.js. This file exports the normalizeProvider function for environment resolution and the connect function for establishing browser sessions. Additional usage documentation is available in docs/browser-runtime.md under the "Provider 선택" section.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}