Skip to content

Add --serve-headless option for bwopencode2 - #44

Open
Eugene M. (genematx) wants to merge 1 commit into
NSLS2:mainfrom
genematx:feat/serve-headless
Open

Eugene M. (genematx) wants to merge 1 commit into
NSLS2:mainfrom
genematx:feat/serve-headless

Conversation

@genematx

Copy link
Copy Markdown

Summary

Adds bwopencode2 --serve-headless: the sandboxed OpenCode 2 web server for another program on the same host, which connects to the published port itself. First user: the Jupyter server extension in NSLS2/n2snassistant, which puts the web UI behind JupyterHub through jupyter-server-proxy.

Compared with --serve:

  • the password must come from BWOPENCODE2_SERVE_PASSWORD (nothing is printed, so a random one would be known to nobody);
  • opencode2 serve runs directly, no pairing links, nothing read from stdin, one start line without secrets;
  • data directory ~/.local/share/opencode2/opencode-web, under the same database guard, so the web server never shares a WAL-mode SQLite database with a terminal session on another host (configuration, skills and agents are shared; sessions are not);
  • the caller pins the port (BWOPENCODE2_SERVE_PORTS=P-P --serve-port P); not combinable with --serve-open.

Mounts, private network, --n2c-token, publish address and port claims are unchanged.

Testing

  • shfmt, shellcheck, markdownlint pass.
  • tests/test-bwopencode2-serve.sh gains dry-run checks for the new option (refused without a password, with --serve-open, with --exec; the server command and the web data directory in the dry run; the password never printed).

Assisted-by: opencode:claude-fable-5-1

…rogram

--serve-headless is --serve for a program on the same host that connects to
the published port itself and signs in with a password it chose: the
JupyterHub single-user server extension in NSLS2/n2snassistant, which puts
the OpenCode web UI behind the Hub through jupyter-server-proxy.

The same sandboxed `opencode2 serve`, mounts, private network and database
guard as --serve, with three differences: the password must come from
BWOPENCODE2_SERVE_PASSWORD (a random one would be known to nobody, since
nothing is printed), the server runs directly instead of the wrapper that
makes pairing links and reads Enter (nothing on stdin, one start line with
no secret in it), and the data directory is
~/.local/share/opencode2/opencode-web, so the web server never shares a
SQLite database, which OpenCode 2 runs in WAL mode, with a terminal session
on another host; the guard would otherwise refuse one of them.
Configuration, skills and agents are shared; sessions are not. The caller
pins the port (BWOPENCODE2_SERVE_PORTS=P-P --serve-port P). Not with
--serve-open.

Documented in docs/bw-wrappers.md; tests/test-bwopencode2-serve.sh gets the
argument and dry-run checks (refused without a password, refused with
--serve-open or --exec, the server command and the web data directory in
the dry run, the password never printed).

Assisted-by: opencode:claude-fable-5-1
Copilot AI balanced review requested due to automatic review settings November 20, 2026 03:40

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Critical issues cause --serve and --serve-open to terminate before sandbox startup and leave web and terminal databases sharing locks and backup state, allowing cross-host blocking and restoration from the wrong database’s backup.

No open issues 🎉

What changed in this PR

Adds bwopencode2 --serve-headless for programs on the same host to launch and access the sandboxed OpenCode 2 web server, supporting the JupyterHub integration in NSLS2/n2snassistant.

Changes:

  • Adds direct server startup with a required caller-provided password and no pairing links or browser launch.
  • Selects a separate web data directory to support isolation from terminal sessions.
  • Documents the integration and adds dry-run checks for arguments, command construction, and password redaction.
File Description
tests/​test-bwopencode2-serve.sh Adds headless-mode validation and dry-run checks.
docs/​bw-wrappers.md Documents headless usage, authentication, storage, and port selection.
bin/​bwopencode2 Implements headless arguments, startup, data-path selection, and help text.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants