swayyyyy/vibebridge/vibebridge-node-install

VibeBridge Node Install

Use this skill when the task is to install, deploy, or reconfigure a VibeBridge Node.

Ask first

Before editing configs/node.toml or starting a long-running process, ask the user for the required deployment values instead of guessing:

• whether the install target is the current machine or a machine reached through SSH
• if the target is remote, the SSH user, host, port, and whether the SSH session is already open
• repo path on the target machine
• whether a fresh isolated environment is required, and the desired venv path
• connection mode:
• main_server_url for direct Node -> Main WebSocket
• main_register_url for HTTP registration followed by Main callback
• the actual Main URL for the chosen mode
• register_token
• node listen host and port
• whether Main can reach the callback address if HTTP registration mode is chosen
• optional node identity overrides: id, name, labels, capabilities
• preferred run style: nohup, systemd, launchd, or manual
• whether Codex must work on this node; if yes, confirm the codex CLI path or install method

If any of the required values are missing, stop and ask. Do not silently invent network addresses, tokens, or service managers.

Defaults and preferences

• Prefer a fresh role-specific venv such as .venv-vibebridge-node.
• For long-running deployment, use python -m uvicorn app:app ....
• Do not use python app.py for production-like runs because the repo entrypoint enables reload=True.
• If the node is not publicly reachable, prefer direct main_server_url mode so the node initiates the outbound connection.
• In HTTP registration mode, Main still needs a reachable callback address. Use advertise_host and advertise_port when the local listen address is not the right callback address.
• The browser should connect only to Main, not to the Node.
• Keep Main and Node on different SQLite files.
• Do not assume local paths apply to a remote machine. If deployment is over SSH, treat the repo path, venv path, logs, and service files as remote paths.

Bundled script

Use the bundled installer when it fits:

• scripts/install_node.sh
• creates the venv
• installs Python dependencies
• writes configs/node.toml
• leaves process supervision to the caller

Do not overwrite an existing configs/node.toml unless the user explicitly asks for that. The script supports --force-config for intentional replacement.

Example for direct WebSocket mode:

bash skills/vibebridge-node-install/scripts/install_node.sh \
  --repo /path/to/VibeBridge \
  --venv /path/to/VibeBridge/.venv-vibebridge-node \
  --mode ws \
  --main-server-url ws://main.example.com:8000/ws/node \
  --register-token <user-node-register-token> \
  --host 127.0.0.1 \
  --port 4456

Example for HTTP registration mode:

bash skills/vibebridge-node-install/scripts/install_node.sh \
  --repo /path/to/VibeBridge \
  --venv /path/to/VibeBridge/.venv-vibebridge-node \
  --mode http \
  --main-register-url http://main.example.com:8000/api/nodes/register \
  --register-token <user-node-register-token> \
  --host 0.0.0.0 \
  --port 4456 \
  --advertise-host node.example.com \
  --advertise-port 4456

Start patterns

Use the run style the user asked for. If they do not care, use the platform default that matches prior local conventions:

• Linux server: systemd for Main, nohup or systemd for Node
• macOS workstation: nohup unless the user explicitly asks for launchd

Typical nohup command:

mkdir -p logs
nohup env PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin \
  ./.venv-vibebridge-node/bin/python -m uvicorn app:app --host 127.0.0.1 --port 4456 \
  >> logs/node.log 2>&1 < /dev/null &

Validation

After installation or config changes:

1. Check local health:

``bash curl -sf http://127.0.0.1:<port>/health ``

1. Confirm the process environment can find codex if Codex support is expected:

``bash command -v codex ``

1. Confirm the Main side shows the node as registered.
2. If the node should be private, verify that no public inbound access is required in direct WebSocket mode.

Notes

• main_server_url and main_register_url are alternatives. Only one should be meaningfully configured.
• If HTTP registration is selected for a private node that Main cannot call back, stop and realign with the user instead of forcing a broken setup.
• Respect existing deployments. Avoid replacing user-managed services, plists, or unit files unless asked.