bare-operating-system/packages/bare-os-seeder/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.