share and lan-guard
share is an experiment: run benchbar labs on lan-rooms first. While the lab is off, share and lan-guard are hidden from --help and commands --json (listed under gated) and exit 2 with that hint. benchbar labs off lan-rooms stops a running share and, if lan-guard is installed, warns with run: benchbar lan-guard remove (it never uses sudo itself).
Sharing opens a room on this Mac’s network. People on the same Wi-Fi join it with a 6 digit room code, take a seat (one of the Frappe users you chose) and use a hardened copy of one of your dev sites in their own browser. macOS only. Every command takes the options for every command. The documents are in the JSON schema.
The safety model in plain words
- Only the copy is shared, never the site.
share setuprestores a backup of the site intoshare.localhostand hardens it. Your site, its database and its files are not reachable from the network. - The bench’s ports stay on this Mac. The LAN guard (a pf anchor,
below) refuses web 8000-8099, socket.io 9000-9099, Redis 11000-11099
and 13000-13099 and MariaDB 3306 to anything but this Mac. Guests reach
only the gateway on port 8443 (TLS, both sides with a certificate). A
request that names any other
Host(DNS rebinding) is refused with 400bad_hostand its connection closed. - Sharing fails closed. Before the gateway starts, and about once a
minute while it runs, the checks (
share preflight --critical, a few seconds per run) probe the block from this Mac’s own LAN address with a throwaway listener and a control port. Two failed runs in a row, or a gateway that exits, end the share. A share web process that ends is started again and checked, with guests seeing a “restarting” page meanwhile; the 4th end in a row (a web that stays up 5 minutes starts the count again) ends the share. - The room code proves membership, not the host’s identity. Anyone who has the code can join, with no action from you; you see every join and can remove people. On a first join a guest cannot tell your room from a rogue one that also knows the code: the guest’s pin of your certificate protects only rejoins.
- Ten wrong codes lock the room until you draw a new code. The count is
for the room, not per guest, so anyone on the network who can reach the
gateway can lock everyone out by guessing wrong ten times. The lock holds
until
share code --new; nobody gets in or back in meanwhile. The code never reaches a file, a log,share statusor any--jsonbutshare code --jsonandshare invite --json. - The copy holds real data (people, customers, contacts, addresses).
share setupstops until you pass--acknowledge-data. - No live updates for guests.
/socket.ioanswers 404 through the gateway, so pages do not refresh by themselves; guests reload. - Sharing ends at its deadline (4 hours by default, at most 12 hours from the start) and when you stop it. Every session of the copy ends with it.
What guests can see
The pages of the copy that their seat’s user can open, and the room’s
roster (In this room: each person’s name, Mac model, seat and whether
they are online). Not your site, not other benches, not the code. Before
they join, a guest sees only the room’s label, your Mac’s name, the site’s
name and the people and seat counts.
What the copy holds, and what is taken out
The copy is your site’s database and files at the backup you choose. In the copy only:
- the seat users lose every role that can run code or change settings
(
share userslists them per user); Website Users are never seats; - every other user is disabled, and Administrator’s password is replaced by a random one nobody is told;
- developer mode, server scripts, sign-up and API keys are off; outgoing mail is muted; Portal Settings’ default role is cleared;
- the copy and its backups are excluded from Time Machine.
The sudo steps
macOS asks for your password (or shows its own dialog when the BenchBar app
runs the command) only for lan-guard install, lan-guard remove and
lan-guard allow-node. Nothing else in sharing runs as root.
share setup
benchbar share setup [--site S] [--from STAMP|latest] [--backup-now] [--users A,B] [--name LABEL] [--refresh] [--regenerate-identity] [--acknowledge-data] [--dry-run] [--yes] [--json]Makes the copy, hardens it and creates the host identity (key and
certificate). --users picks the seats (enabled System Users).
--refresh replaces an existing copy (backed up first); it is needed to
change the seats. Refused under BENCHBAR_NONINTERACTIVE, --for-agent
and mcp, and without a terminal unless the app passes BENCHBAR_SUDO=gui.
Making the copy (the first setup, or --refresh) restores it as MariaDB’s
root user, so it needs the root password: from the Keychain, from
MARIADB_ROOT_PASSWORD, or typed at a terminal (setup asks for it before
anything changes, and keeps it in the Keychain). Without a terminal, with
--yes or --json, and with no password known, setup and its dry run stop
before any change with exit 2, naming MARIADB_ROOT_PASSWORD. A MariaDB
root that logs in only over the unix socket, with no password, cannot make
the copy.
A setup that stops halfway (a failed step, or the app quit while it ran)
never leaves the bench’s scheduler paused: the pause it set for the restore
is removed on the way out, and the half-made copy keeps a pause_scheduler
and mute_emails of its own. A pause that was there before setup started
stays. Such a setup leaves no share.json: until share setup --refresh
finishes it, share status, share start and a plain share setup say
“Sharing setup was interrupted. Run: benchbar share setup —refresh”.
Exit codes: 0; 1 on a refusal or a failed step; 2 when the MariaDB root password is needed and unknown.
benchbar share setup --site mysite.localhost --users priya@example.com,mgr@example.com --acknowledge-datashare users
benchbar share users [--site S] [--json]The users who can take a seat, and the roles each would lose in the copy. Reads only.
benchbar share users --site mysite.localhostshare preflight
benchbar share preflight [--static|--critical] [--quiet] [--json]The checks, each with a status, a message and a fix_action. --static:
what is checked before anything starts (the copy, its seats, node, the
firewall). --critical: what a running share repeats (the pf block probed
from the LAN address, the share web process, the bench’s Redis).
Exit codes: 0 when every check passes; 1 when one fails.
benchbar share preflight --criticalshare start
benchbar share start [--for DUR] [--name LABEL] [--dry-run] [--json]Starts the room until the deadline (--for 30m, 4h; 5 minutes to 12
hours; 4 hours by default). The bench must be running. Refused like
share setup. A second start says “unchanged”.
A start takes about 15 seconds on a 29-app copy: the checks run before and after the gateway starts (about 2 seconds each), and the copy’s web process is started and warmed with one request before them (1 to 10 seconds, longer for a cold large copy; up to 30 seconds are allowed). A restart of the web process while sharing takes about 10 seconds, during which guests see the “restarting” page.
benchbar share start --for 2hshare code
benchbar share code [--new] [--json]Prints the room code on the terminal, for you to read out. --new draws a
new one: the failure budget resets, people already in the room stay, and a
code already handed out stops working. --json is the app’s read: the one
document that carries the code. Never logged and never stored.
Refused under BENCHBAR_NONINTERACTIVE, --for-agent and mcp, and
without a terminal unless the app passes BENCHBAR_SUDO=gui, so a script,
a cron job or an agent’s shell never reads the code.
benchbar share code --newshare invite
benchbar share invite [--install-url URL] [--json]Prints a ready-to-paste invite for your team channel. Its link carries the room’s name, this Mac’s key fingerprint, the code’s salt, the code itself, this Mac’s LAN address and gateway port, and the deadline, so a guest’s BenchBar opens the join sheet with everything filled in. The guest still clicks Join. Before the code is sent, the guest’s app checks that the host’s key matches the fingerprint in the link and that the salt is still current.
Join my BenchBar room "Lab" (office Wi-Fi, until 17:30)benchbar://share/join?v=1&r=Lab&h=<64 hex>&s=<32 hex>&c=<6 digits>&a=192.168.1.20%3A8443&x=<unix seconds>No BenchBar yet? Install: <URL>Or: open BenchBar → On your network → Paste inviteThe install line is there only with --install-url, which must be one
http:// or https:// address with no spaces. --json gives
url, text, expires_at (ISO 8601, UTC) and room. Every link
value is percent-encoded (a space is %20).
The invite holds the room code. Anyone who gets the text can join
until sharing ends. Post it only where the people you mean to invite read
it. New code (share code --new, or share remove --new-code) or
Stop makes every posted invite stop working: a guest with an old invite is told to ask for a new one, and
does not use up one of the room’s ten tries. The app’s Copy invite puts
the text on the clipboard only when you click it.
It has the same guards as share code: refused for agents and scripts,
never logged and never stored. It needs sharing on with the site up, and
says “start sharing first” if it is not. It also needs an IPv4 address on
this Mac’s default network.
benchbar share invite --install-url https://example.com/benchbarshare lock and share unlock
benchbar share lock [--json]benchbar share unlock [--json]Lock: nobody new can join. The room also locks itself while every seat is
taken. Unlock lifts your lock; a lock after 10 wrong codes stays until
share code --new.
benchbar share lockshare people
benchbar share people [--json]The people in the room: id (d_ and 8 hex digits), name, Mac model,
address, seat, online, joined, last seen. share devices is another name
for it.
benchbar share peopleshare remove
benchbar share remove ID [--new-code] [--yes] [--json]Removes a person: their seat’s sessions end and their Mac cannot join
again with the code it used. Drawing a new code (share code --new, the
app’s Copy new invite) lifts every removal, so to let someone back in,
send them the new invite; the people still in the room stay. Asks first.
--new-code also draws a new code, for when you do not know who it was: a
fresh Mac could join again with the old one. share revoke is another name
for it.
benchbar share remove d_0123abcd --new-codeshare assign
benchbar share assign ID SEAT_ID [--json]Moves a person to another free seat; the old seat’s sessions end first.
benchbar share assign d_0123abcd s_0a1b2c3dshare log
benchbar share log [--device ID] [--since TIME] [--limit N] [--json]What people in the room opened in the last 14 days: time, Mac, seat, method, the first two path segments (never a document name) and the status. 200 entries by default, at most 5000.
benchbar share log --device d_0123abcd --since 09:00:00share open-as
benchbar share open-as USER [--print-url] [--json]Opens the copy in this Mac’s browser signed in as a seat, the way
open --as does (the copy is opted in to Open as by share setup).
--print-url prints the sign-in link instead: it carries the session id,
so treat it like a password. The link goes to the copy’s own web port on
this Mac (http://share.localhost:PORT/login?...), not through the
gateway. --json never includes the link or the session.
Refused under BENCHBAR_NONINTERACTIVE, --for-agent and mcp, and
without a terminal unless the app passes BENCHBAR_SUDO=gui.
benchbar share open-as priya@example.comshare status
benchbar share status [--preflight] [--json]on, off, expired or error, the time left, the copy, the room’s
counts (seats, people, locked, budget_left, join_trouble) and the
LAN guard’s state. Never the code. --preflight adds the critical checks.
setup_interrupted is true when a setup stopped halfway: there is no
share.json, and the one setup set aside or the copy share.localhost is
there. Only share setup --refresh clears it.
wipe_failed counts a sign-out that is owed or failed. While sharing is
off it reads 1 or more from the marker share stop leaves when it could
not end every session of the copy (the next room command retries it while
the bench’s Redis answers). It also reads 1 for a moment after every
share remove, until the gateway has ended that seat’s sessions.
benchbar share status --jsonshare extend
benchbar share extend --by DUR [--json]Moves the deadline, up to 12 hours from the start.
benchbar share extend --by 1hshare stop
benchbar share stop [--json]Ends the room: the gateway and the job stop, the room empties and every session of the copy ends. Never refused, no dry run.
benchbar share stopshare teardown
benchbar share teardown [--yes] [--json]Stops sharing, drops the copy (backed up first) and deletes the share folder with the host identity and the room. Asks first. The archived copy keeps its Time Machine exclusion.
benchbar share teardown --yeslan-guard install
benchbar lan-guard install [--dry-run] [--yes] [--json]Writes the pf anchor /etc/pf.anchors/com.benchbar.lan (loaded as
com.apple/250.benchbar) and the launch daemon
/Library/LaunchDaemons/com.benchbar.pf.plist that loads it at every boot,
with sudo once, then probes the block from the LAN address. Says
“unchanged: the guard is installed and matches”, with no sudo, when the
anchor and the daemon already match and no bench port answers on the LAN.
When they match but a bench port answers (pf disabled, the anchor flushed),
it loads the anchor and the daemon again with sudo, and fails if a port
still answers. Refused under BENCHBAR_NONINTERACTIVE,
--for-agent and mcp, and without a terminal unless BENCHBAR_SUDO=gui.
On a refusal, run the same command yourself in a terminal.
Turning pf on (pfctl -E) hands out a token. Install records it in the
state folder (lan-guard/pf.state, never the bench), together with whether
pf was already on before the first install, so that lan-guard remove can
give it back.
What lan-guard blocks. The rule is global and always on, with or without
a room open: TCP to ports 8000-8099 (web), 9000-9099 (socket.io),
11000-11099 and 13000-13099 (Redis) and 3306 (MariaDB) is refused unless it
comes from this Mac’s loopback address. Anything that reaches those ports
through this Mac’s LAN address is refused too, which includes a Docker
container or a VM that dials the LAN IP instead of the loopback one. Use
127.0.0.1 where the tool allows it, or run benchbar lan-guard remove for as
long as you need the LAN path (share start refuses to run without the
guard, so install it again before you share). lan-guard allow-node is not
a way around the block: it only lets the gateway’s node through the macOS
application firewall and opens no bench port.
Exit codes: 0; 1 on a refusal, a cancelled password, a failed root step or a block that still lets a bench port through.
benchbar lan-guard install --dry-runlan-guard status
benchbar lan-guard status [--json]installed, missing or outdated, and active: whether the bench ports
are refused on this Mac’s LAN address (null with no LAN address). Reads
only; never refused.
benchbar lan-guard status --jsonlan-guard remove
benchbar lan-guard remove [--yes] [--json]Unloads and deletes the anchor and its daemon, with sudo once. Asks first.
Without them the bench ports answer the LAN and share start refuses to
run.
It also gives back the pf token that install recorded (pfctl -X TOKEN), so
pf is turned off again when the guard was the only thing that turned it on.
When pf was already enabled before the first install, remove leaves pf on.
A token from before a reboot is stale, and releasing it is harmless. The
boot daemon takes a reference of its own at every boot; it ends at the next
reboot, because remove deletes the daemon.
benchbar lan-guard removelan-guard allow-node
benchbar lan-guard allow-node [--yes] [--json]Adds the realpath of the node the gateway runs on to the macOS firewall’s
allowed apps, with sudo once. “Unchanged” when the firewall is off or
already allows it. A Homebrew upgrade of node changes the realpath, so the
firewall_node check asks for it again.
benchbar lan-guard allow-node