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

> Explore k-skill browser providers including auto, browseros, aside, and chrome-cdp. Learn how to configure the browser runtime for optimal performance.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: tutorial
- Published: 2026-08-03

---

**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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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

```javascript
// 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

```javascript
// 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

```javascript
// 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`](https://github.com/NomaDamas/k-skill/blob/main/provider.js) lines 18–23.
- **Source location**: Provider logic resides in [`packages/k-skill-browser-runtime/src/provider.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-browser-runtime/src/provider.js), with documentation available in [`docs/browser-runtime.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/docs/browser-runtime.md) under the "Provider 선택" section.