dsh-bsk-daemon
A DeepSeek Harness (DSH) bundle that gives the BrowserSkill bsk bridge daemon the same lifecycle as DSH: it starts with DSH, is stopped when DSH exits, is restarted after a crash (bounded), and is never confused with a daemon somebody else started.
This is a community companion to the upstream Tencent/BrowserSkill project — see Acknowledgements.
Runs on Windows, macOS and Linux — see Platform support.
中文说明 · Agent instructions · 中文 Agent 说明
Why this exists
BrowserSkill exposes browser automation to DSH through bsk_* tools backed by a local bsk daemon. Some agent hosts run shell commands in a sandbox that reaps or forbids the daemon. The concrete Windows case:
- a sandboxed child cannot break away from the Windows job object,
- it cannot write
~/.bsk,
- it cannot open the daemon's IPC endpoint.
Linux agents hit the equivalent problem with bubblewrap-style sandboxes that kill command children. The documented workaround is to keep the daemon in a persistent host context and use local IPC from the sandbox — which is exactly what a supervisor in the DSH host process provides.
This bundle moves that responsibility into DSH itself: the daemon becomes a DSH child with a DSH lifetime.
Platform support
| Platform | Status | Notes |
|---|
| Windows 10/11 x64 | Verified end to end | Daemon started, stopped, restarted through the plugin in real use; job object also reaps it if DSH dies. |
| macOS (Apple Silicon / Intel) | Supported, not yet run on real hardware | Same code path; IPC is a Unix domain socket, bsk daemon stop and signal handling are cross-platform. |
| Linux x64 / ARM64 | Supported, not yet run on real hardware | Same as macOS; the bubblewrap sandbox case is the closest analogue to Windows. |
| Node.js 22+ | CI matrix | The test suite runs on ubuntu-latest, macos-latest, windows-latest for Node 22 and 24. |
Confirmed by the test matrix: module load, config validation, effect registration order and awaitable disposal on all three operating systems. A real bsk daemon is only exercised on Windows so far; a Unix run needs a machine with the CLI and the browser extension.
Compatibility
| Component | Supported | Tested with |
|---|
| DeepSeek Harness | 0.2.x profiles with bundle support | 0.2.1-rc.2 |
| Cordis plugin API | 4.x (ctx.effect, standard-schema Config) | 4.0.5 |
BrowserSkill bsk | 0.3.x | 0.3.3 |
| Node.js | >=22 | 22, 24 (CI), 26 (local) |
Older DSH releases that do not support profile bundles cannot load this package; use the local checkout install only if your DSH supports plugin_manager install_bundle.
Installation
From GitHub Packages
The package is published to GitHub Packages as @xfy9326/dsh-bsk-daemon. GitHub requires authentication even to read public packages, so first make a token with read:packages available to npm:
npm config set @xfy9326:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken $env:GITHUB_TOKEN
or interactively:
npm login --scope=@XFY9326 --registry=https://npm.pkg.github.com
Then ask your DSH agent to install the bundle:
Install @xfy9326/dsh-bsk-daemon from https://npm.pkg.github.com with plugin_manager install_bundle.
The tool records the dependency in the active profile, applies the bundle patch, and should report application: applied. You can also run it directly:
{
"action": "install_bundle",
"target": "@xfy9326/dsh-bsk-daemon",
"registry": "https://npm.pkg.github.com"
}
Do not install it with plain pnpm add / dsh plugin add alone: those only add the dependency, they do not enable the bundle layer.
From a local checkout
git clone https://github.com/XFY9326/dsh-bsk-daemon.git C:\Tools\dsh-bsk-daemon
Then ask your DSH agent to install the bundle at that absolute path with plugin_manager install_bundle. The profile gets a link: dependency, so the checkout must not be moved afterwards.
After install
bsk status --json
The daemon should be reported as a child of the DSH host process. The plugin row appears in DSH Settings → Plugins as bsk Daemon Supervisor / bsk 守护进程托管.
A DSH restart is normally not required (the bundle is applied through HMR), but restart if the row does not appear.
Configuration
The bundle inserts one row with no config; the defaults are:
| Key | Default | Meaning |
|---|
bskPath | bsk | Executable name on PATH, or an absolute path |
bskHome | $BSK_HOME or ~/.bsk | Where daemon.json, the IPC endpoint and logs live |
args | daemon start --foreground --daemon-idle 30d | Arguments passed to bskPath |
To override, edit this bundle's cordis.patch.yml before installing:
- insert:
- id: bsk-daemon
name: '@xfy9326/dsh-bsk-daemon'
config:
bskPath: 'C:\Tools\bsk\bsk.exe'
bskHome: 'C:\Users\me\.bsk'
args: [daemon, start, --foreground, --daemon-idle, 30d]
Row config is replaced wholesale. If the daemon should never be started by DSH (for example you run a shared daemon yourself), disable the row instead.
Cross-platform behaviour
The plugin only uses Node.js built-ins (child_process, net, fs, os, path), so no platform branching is needed in the code:
- Probing reads
daemon.json and connects to sock_path. On Windows that is a named pipe (\\.\pipe\bsk-daemon-*); on macOS/Linux it is a Unix domain socket (~/.bsk/run/daemon.sock). net.connect() handles both.
- Stopping uses the same CLI on every platform (
bsk daemon stop), only when daemon.json's pid is this plugin's own child, then falls back to a signal.
- Lifecycle difference: Windows job objects also reap the daemon if DSH is killed hard. On macOS/Linux there is no such mechanism, so a hard-killed DSH leaves the daemon running; the next DSH start probes it and reuses it instead of starting a second one. A normal DSH exit stops it through the plugin either way.
windowsHide is a Windows-only spawn option; it is ignored elsewhere.
Verification
# Is the daemon up and serving?
bsk status --json
# Is it a child of the DSH host process? (Windows)
Get-CimInstance Win32_Process -Filter "Name='bsk.exe'" | Select-Object ProcessId, ParentProcessId, CommandLine
# The same on macOS/Linux
pgrep -fl 'bsk daemon start --foreground'
# Daemon log, written by bsk itself
Get-Content "$env:USERPROFILE\.bsk\daemon.log.*" -Tail 20 # Windows
tail -n 20 ~/.bsk/daemon.log.* # macOS/Linux
Expected: one daemon process whose parent is the DSH process, a listening loopback port (default 52800), and daemon.json containing sock_path plus host_managed: true.
To exercise the lifecycle end to end:
# restart it behind the plugin's back; the plugin should bring it back within a few seconds
bsk daemon stop --json
Start-Sleep 5
bsk status --json
How it works
DSH host process
└── plugin row: bsk-daemon (@xfy9326/dsh-bsk-daemon)
└── bsk daemon start --foreground --daemon-idle 30d
├── ~/.bsk/daemon.json (pid, sock_path, ws_port)
├── IPC endpoint (named pipe / Unix socket)
└── ws://127.0.0.1:52800 (browser extension)
Startup probes daemon.json and connects to sock_path before spawning anything, so a daemon started by another host or by hand is reused instead of duplicated. Shutdown uses the CLI stop only when the recorded pid is this plugin's own child, so a foreign daemon is never signalled.
Troubleshooting
| Symptom | What to check |
|---|
bsk_* tools still report no daemon | Is the bsk-daemon row enabled? Run bsk status --json; inspect the DSH log for [bsk-daemon] lines |
| Daemon exits immediately | Run the configured command manually (bsk daemon start --foreground) to see the error; check bskPath |
Install fails with 401/403 from npm.pkg.github.com | Your npm token is missing or lacks read:packages; redo the auth step |
| Two daemons appear | Only the plugin's own child is managed. A foreign daemon is deliberately left alone; stop it yourself if it is stale |
bsk status works but bsk_* tools fail | Restart DSH so the browser-skill plugin reconnects to the managed daemon |
| Restart loop, then silence | The plugin gives up after 5 consecutive failures; fix the underlying error and restart DSH (or toggle the bundle) |
Uninstall
Ask your DSH agent to remove the bundle (plugin_manager remove_bundle, target @xfy9326/dsh-bsk-daemon), or disable it to stop the daemon while keeping the files.
Security notes
- The bundle only spawns the
bsk binary you configure; no downloads, no install scripts.
- It opens no new network listeners; the daemon's loopback port and IPC endpoint belong to BrowserSkill.
- No credentials are read or stored. The config schema is limited to three plain fields.
Development
node --test # zero-dependency test suite (node:test)
npm pack --dry-run # inspect the published file set
CI: .github/workflows/test.yml runs the suite on Ubuntu, macOS and Windows for Node 22 and 24. Pushing a v* tag runs .github/workflows/publish.yml, which tests, publishes to GitHub Packages and creates a GitHub Release with the packed tarball.
Acknowledgements
This bundle is a community add-on built on top of Tencent/BrowserSkill, the upstream project that provides the bsk CLI, daemon, browser extension and the DSH bsk_* tools. Thanks to its authors and contributors for the daemon design and documentation — in particular the sandboxed-agent guide that shaped this supervisor.
BrowserSkill is not modified or redistributed here; install and use it under its own license. This repository is not affiliated with or endorsed by Tencent.
License
MIT
