Notes Browser Installation & Socket Mode Setup

Quick start (kelp)

Script: /home/john/git/gdata-server/notes-browser/notes_browser.py. Display: DISPLAY=:1 XAUTHORITY=/home/admin/.Xauthority. Two stores — public (8021) and private (8121).

# Public notes
DISPLAY=:1 XAUTHORITY=/home/admin/.Xauthority \
  /home/john/git/gdata-server/notes-browser/notes_browser.py \
  --url http://127.0.0.1:8021 \
  --control-tcp-enabled --control-tcp-port 8711 &

# Private notes (db.com / sensitive)
DISPLAY=:1 XAUTHORITY=/home/admin/.Xauthority \
  /home/john/git/gdata-server/notes-browser/notes_browser.py \
  --url http://127.0.0.1:8121 \
  --control-tcp-enabled --control-tcp-port 8711 &

Then navigate and capture via RPC (wait a few seconds for the browser to initialise before connecting):

import socket, json, time

def rpc(m, p=None):
    s = socket.socket()
    s.settimeout(5)
    s.connect(('127.0.0.1', 8711))
    s.sendall((json.dumps({'jsonrpc':'2.0','id':1,'method':m,'params':p or {}}) + '\n').encode())
    r = json.loads(s.recv(65536))
    s.close()
    return r

rpc('navigate.go_to_page', {'key': 'dap/portal-schema/backfill-progress'})
time.sleep(2)
rpc('ui.capture_content', {'path': '/home/john/dbdb/evidence/screenshot.png'})

Port map (kelp)

8021 — public notes browser-facing (stunnel → gravlax:18021)
8121 — private notes browser-facing (stunnel → gravlax) ← use this for private store
8024 — private notes MCP API (not for browser)
8124 — private notes MCP API (not for browser)
8711 — notes_browser TCP control (JSON-RPC 2.0)

Installation

# Install wxPython dependency
bash -i -c "pipin wxPython"
# Script is in git, not installed as a package:
# /home/john/git/gdata-server/notes-browser/notes_browser.py

# Install wxPython dependency
bash -i -c "pipin wxPython"

# Install notes-browser package in development mode
cd /home/john/py/envoy/notes-browser
bash -i -c "pipin -e ."

The pipin alias is defined as:

pipin='pip install --user --break-system-packages'

Always use this alias rather than direct pip commands, and do NOT suggest environment variable configuration.

Socket/Server Mode

Notes Browser supports three control transports for remote operation:

Control Transports

TCP: Line-delimited JSON-RPC 2.0 over TCP socket (port 8711 default)
UDP: JSON-RPC 2.0 over UDP datagrams (port 8711 default)
Unix Domain Socket: Line-delimited JSON-RPC 2.0 over Unix stream socket

DISPLAY=:1 XAUTHORITY=/home/admin/.Xauthority \
  /home/john/git/gdata-server/notes-browser/notes_browser.py \
  --control-tcp-enabled --control-tcp-port 8711 --url http://127.0.0.1:8021

DISPLAY=:1 XAUTHORITY=/home/admin/.Xauthority \
  /home/john/git/gdata-server/notes-browser/notes_browser.py \
  --control-unix-enabled --control-unix-socket /tmp/notes-browser.sock \
  --url http://127.0.0.1:8021

Example Usage

Run notes browser with TCP control enabled on port 8711:

cd /home/john/py/envoy/notes-browser
python3 notes_browser.py --control-tcp-enabled --control-tcp-port 8711 --url http://127.0.0.1:8021

Run with Unix domain socket for local control:

cd /home/john/py/envoy/notes-browser
python3 notes_browser.py --control-unix-enabled --control-unix-socket /tmp/notes-browser.sock --url http://127.0.0.1:8021

Configuration File

Settings can also be configured via ~/.notes_browser.yaml:

notes_url: http://127.0.0.1:8021
control_tcp_enabled: true
control_tcp_port: 8711
control_udp_enabled: false
control_unix_enabled: false

JSON-RPC Control API

Complete API documentation with all 30 RPC methods, parameters, examples, and error handling is at: setup/notes-browser-api

Complete API documentation is available at: setup/notes-browser-api - includes all 30 RPC methods with signatures, parameters, examples, and error handling.

Socket Mode History

Socket/server mode was restored from git history (host kelp: /home/john/git/gdata-server/notes-browser/notes_browser.py) on 2026-07-19. The feature provides JSON-RPC 2.0 control interface for remote browser automation and integration.