# How k-skill Uses CloakBrowser in Browser Mode: Runtime Detection and Execution

> Discover how k-skill uses CloakBrowser for runtime detection and execution. Learn about its environment variable inspection and fallback mechanisms for seamless browser integration.

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

---

**k-skill automatically detects CloakBrowser availability through environment variable inspection in the `detectRuntime` function, prioritizing the built-in browser tool when `CLOAKBROWSER_PEEK_TOKEN` or `DOLSHOI_ACTION_BROKER_URL` is present, while falling back to the portable `k-skill-browser-runtime` in generic environments.**

The **k-skill** framework from NomaDamas/k-skill provides intelligent browser automation capabilities through its **browser mode**, which dynamically selects between the built-in CloakBrowser tool and portable runtime alternatives. This capability-based detection system ensures that skills running on Dolshoi-enabled agents leverage credential-aware browsing, while maintaining compatibility with standard environments. Understanding how k-skill detects and utilizes CloakBrowser requires examining the runtime detection logic and execution hierarchy implemented in the CLI source code.

## Runtime Detection via `detectRuntime`

The core detection logic resides in [`packages/k-skill-cli/src/detect.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/detect.js), where the `detectRuntime` function inspects process environment variables to determine browser capabilities.

```js
function detectRuntime(env = process.env) {
  const dolshoi = Boolean(env.DOLSHOI_ACTION_BROKER_URL);
  const cloakBrowser = Boolean(env.CLOAKBROWSER_PEEK_TOKEN) || dolshoi;
  return {
    mode: dolshoi ? "dolshoi" : "generic",
    dolshoi,
    cloakBrowser,
  };
}

```

This function evaluates two critical environment signals:

- **`DOLSHOI_ACTION_BROKER_URL`**: Indicates the agent is running in **Dolshoi mode** with full credential access, which implicitly includes CloakBrowser capabilities.
- **`CLOAKBROWSER_PEEK_TOKEN`**: Explicitly signals that the built-in CloakBrowser tool is available for use.

The returned object contains a `mode` field (either `"dolshoi"` or `"generic"`) and a boolean `cloakBrowser` flag that drives subsequent execution decisions throughout the CLI.

## CloakBrowser Priority and Fallback Strategy

According to the design documentation in [`docs/dolshoi-runtime.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/dolshoi-runtime.md) and [`docs/browser-runtime.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/browser-runtime.md), k-skill implements a strict priority hierarchy for browser selection.

In **Dolshoi runtime** environments, CloakBrowser serves as the **primary browser tool**, with the generic portable runtime acting only as a contingency. The [`docs/browser-runtime.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/browser-runtime.md) file states: "Dolshoi uses the built-in CloakBrowser-backed tool as the primary browser; other environments fall back to k-skill-browser-runtime."

For **generic runtime** environments, the framework checks for `CLOAKBROWSER_PEEK_TOKEN` presence. When detected, CloakBrowser takes precedence; otherwise, the system deploys the portable `k-skill-browser-runtime` which interfaces with BrowserOS, Aside REPL, or Chrome CDP.

## Instruction Assembly and User Feedback

When assembling skill instructions in [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js), the CLI surfaces runtime information to users through the `assemble` function. The generated instructions include a diagnostic header:

```

Runtime mode: <mode> (CloakBrowser available)

```

This transparency allows developers to confirm which browser implementation will handle their skill's web automation tasks before execution begins.

## Skill Execution Flow

During actual skill execution, the CLI follows a deterministic resolution path:

1. **Detection**: Invoke `detectRuntime` to assess the environment.
2. **Capability Check**: If `runtime.cloakBrowser` is `true`, initialize the agent's built-in `browser` capability.
3. **Fallback**: Otherwise, load the portable runtime (`k-skill-browser-runtime`) for browser session management.

This flow ensures **CloakBrowser is always the first choice when available**, delivering consistent, credential-aware browsing on Dolshoi-enabled agents while maintaining portability across standard environments.

### Implementation Example: Detecting Runtime in Node.js

```js
const { detectRuntime } = require("@nomadamas/k-skill-cli/src/detect");

// Simulate CloakBrowser availability
const env = { CLOAKBROWSER_PEEK_TOKEN: "token123" };
const runtime = detectRuntime(env);

console.log(runtime);
// → { mode: "generic", dolshoi: false, cloakBrowser: true }

```

### CLI Assembly Example

```bash

# Assemble instructions for a skill

npx -y @nomadamas/k-skill@0 exec korean-cinema-search scripts/assemble.js

# Output includes:

# Runtime mode: generic (CloakBrowser available)

```

## Summary

- **k-skill** detects CloakBrowser through environment variable inspection in [`packages/k-skill-cli/src/detect.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/detect.js).
- The **`detectRuntime`** function checks for `DOLSHOI_ACTION_BROKER_URL` (Dolshoi mode) or `CLOAKBROWSER_PEEK_TOKEN` (explicit token).
- **CloakBrowser receives priority** over the portable runtime when available, ensuring credential-aware browsing on Dolshoi agents.
- The **`assemble`** function in [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js) exposes runtime status in generated instructions.
- Generic environments fall back to **`k-skill-browser-runtime`** when CloakBrowser tokens are absent.

## Frequently Asked Questions

### How does k-skill detect if CloakBrowser is available?

k-skill uses the **`detectRuntime`** function in [`packages/k-skill-cli/src/detect.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/detect.js) to check for the `CLOAKBROWSER_PEEK_TOKEN` environment variable. If this token is present, or if the agent is running in Dolshoi mode (indicated by `DOLSHOI_ACTION_BROKER_URL`), the framework sets `cloakBrowser` to `true` and prioritizes the built-in browser tool.

### What is the difference between Dolshoi mode and generic mode in k-skill?

**Dolshoi mode** activates when the `DOLSHOI_ACTION_BROKER_URL` environment variable is present, indicating the skill runs on a credential-enabled agent that always includes CloakBrowser capabilities. **Generic mode** represents standard environments where CloakBrowser is only available if explicitly configured via `CLOAKBROWSER_PEEK_TOKEN`, otherwise falling back to the portable browser runtime.

### Can I use k-skill browser mode without CloakBrowser?

Yes. When `CLOAKBROWSER_PEEK_TOKEN` is absent and the agent is not Dolshoi-enabled, k-skill automatically falls back to the **`k-skill-browser-runtime`** package. This portable runtime connects to alternative browser infrastructures like BrowserOS, Aside REPL, or Chrome CDP to execute web automation tasks.

### Where can I verify which browser runtime my skill will use?

Check the assembled instruction output from [`packages/k-skill-cli/src/assemble.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/src/assemble.js). The generated instructions include the line `Runtime mode: <mode> (CloakBrowser available)` when the built-in browser is detected, or indicate the generic mode when using the fallback runtime.