bare-operating-system/kernel/share/agent-workspace/skills/holesail/SKILL.md

name, version, description, tags, requires

name	version	description	tags	requires
bare-os-holesail	1.0.0	Holesail P2P tunnels in Bare OS — managed state (seed/key), initd bare-holesail, stock bare-www-* and bare-ssh-* rows, env toggles, ctx.bare.holesail for /bin scripts.	holesail p2p tunnel initd bare-modules	read_man_page read_file read_proc_file

bare-os-holesail Skill

When to use

Use when the user asks about Holesail in this repo: exposing TCP/UDP through Holepunch-style tunnels, /bin/holesail CLI, bare-holesail initd, BARE_OS_HOLESAIL_* environment variables, ctx.bare.holesail from drive bundles, ~/.holesail/state.json persistence (seed / key), or licensing (upstream holesail is AGPL-3.0).

Mental model

1. Integration lives in packages/bare-os-booter/lib/bare-holesail.js (initd + optional early “kernel-path” instance), bare-holesail-managed.js ( state.json rows, ensure, SyncPersistedServerKey ), holesail-cli.js (ctx.bareOsRunHolesailCli for /bin/holesail), bare-os-www-holesail.js, bare-os-ssh-holesail.js.
2. Resolution order under pear run: the booter prefers ctx.bare.holesail ( /lib/bare/bundles/holesail.js after drive merge), else host import.meta.resolve('holesail'), else eval of the drive IIFE bundle via ctx.vfs — /bin and /boot/init.js are not Node modules, so scripts must not require('holesail').
3. Stock default: initd unit bare-holesail is on when BARE_OS_HOLESAIL_INITD and BARE_OS_HOLESAIL_MANAGED are left at defaults (1 in stock shellEnv unless the host clears them). Disable with BARE_OS_HOLESAIL_INITD=0 or systemctl disable bare-holesail (**~/.config/bare-os/initd/disabled.txt**).
4. Stock auto-rows — bare-www-<port> after bare-os-www listens (BARE_OS_WWW_HOLESAIL=0 disables merge). bare-ssh-<port> after bare-openssh listens (BARE_OS_SSH_HOLESAIL=0 disables). bare-user-session-stack re-ensures SSH tunnel after bare-holesail starts if sshd was already listening.

Managed state (state.json)

• Default path — BARE_OS_HOLESAIL_STATE unset → **~/.holesail/state.json** (logical, under **$HOME**). Override env for a different logical path.
• Legacy merge — If the primary file is empty/missing: /.bare/holesail/state.json, /.bare/holesail/guest/state.json, /home/guest/.holesail/state.json are merged once.
• seed — Stable ctor secret: 64-char hex, or valid z32 suffix (migrated from legacy hs://…-only rows). Never replace seed with only the URL suffix written as ctor input.
• key — Full shareable hs://… URL; written/updated after ready() (bareHolesailManagedSyncPersistedServerKey). holesail list shows live URL when tunnel runs.
• Daemon — First startManagedConnectionsFromDisk pass starts all rows; yield one tick; second pass uses onlyNew so bare-os-www / bare-openssh can append rows without tearing down tunnels already started.

Managed vs single-tunnel mode

• Managed (default) — BARE_OS_HOLESAIL_MANAGED=1. Operator CLI: holesail list, add, remove, start, stop, restart, enable, disable, path, help.
• Single tunnel — BARE_OS_HOLESAIL_MANAGED=0, then exactly one of BARE_OS_HOLESAIL_SERVER=1 or BARE_OS_HOLESAIL_CLIENT=1, and in client mode BARE_OS_HOLESAIL_KEY=…. Optional: BARE_OS_HOLESAIL_SECURE, PORT, HOST, UDP, LOG.

Early booter (“kernel-path”) instance

Separate from initd: enable with BARE_OS_HOLESAIL_KERNEL=1 and the BARE_OS_HOLESAIL_KERNEL_* mirror env vars. Starts after the repl boot phase and before startBareInitd; teardown uses registerKernelShutdownHook. **hs.pause() / hs.resume()** tie into mobile suspend/resume.

Operator CLI quick reference

From holesail-cli.js help text:

• holesail add ID --server|--client with optional --key, bare hs://… token (no --key prefix), --port, --host, --udp, **--secure / --no-secure**, --log.
• holesail remove ID, **start|stop|restart ID**, **enable|disable ID**.

Managed bare-holesail starts after kernel-logger and bare-os-www by default. Logs: /var/log/bare-os/holesail.log. Example unit drop-in: /etc/bare-os/units/bare-holesail.unit.example.

Debugging and safety

• BARE_OS_HOLESAIL_DEBUG=1 — extra console lines (URLs only; keys are not logged in full).
• Do not paste full connection secrets into chat or commit logs; redact hs:// payloads when summarizing.
• read_man_page holesail (after a coreutils/man build); handbook/04-the-booter-runtime.md § bare-holesail, § bare-os-www, § bare-openssh — prose source of truth.

Execution steps (for the agent)

1. Confirm whether the question is operator tunnels (CLI + state file + initd) vs guest scripting (ctx.bare.holesail).
2. If live behavior matters, prefer read_proc_file / initd journal paths the user can access over guessing from docs.
3. Mention AGPL when the user plans to redistribute or ship a product that bundles holesail.

Constraints

• Read-only unless the user explicitly authorizes changing env, initd disables, or holesail add state.
• Do not assume holesail is import()-able from pear: without ctx.bare or the drive bundle.