Contributing

Fixes, new nodes, docs and tests are all welcome, and small, focused pull requests are the quickest to review. This page is the short version; CONTRIBUTING.md in the repo is the full one.

Before you start

A bug fix or a small change can go straight to a pull request. For anything bigger, like a new core node or a change to the runtime, open an issue or a post in Discussions Ideas first, so we agree on the shape before you spend time on code.

Set up

You need Python 3.11, 3.12 or 3.13, Node.js 20 or newer for editor work, and Git.

git clone https://github.com/Boltjar/Boltjar.git
cd Boltjar
python3 -m venv .venv          # on Windows: py -3.12 -m venv .venv
source .venv/bin/activate      # on Windows: .\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
npm ci --prefix editor
npm run build --prefix editor
python -m boltjar serve

python -m boltjar serve starts the server and opens the editor at http://127.0.0.1:8770 (--no-browser skips that, --verbose prints every request and full tracebacks). The server serves the built editor from editor/dist, so rebuild after an editor change. For hot reload while you work on the editor, keep the server running, run npm run dev --prefix editor in a second terminal and open http://localhost:5173; Vite forwards /api and /ws to port 8770.

Run the tests

python -m pytest -q
npm test --prefix editor
npm run build --prefix editor

The editor build runs the type check first. The Python suite needs no API keys and no running Ollama: a node that calls a vendor is tested through the vendor_http fixture, which records the real request and answers with whatever the test sets. CI runs the same commands on every pull request, on Linux, Windows and macOS.

Add a node

Core nodes live in boltjar/nodes/core/builtin.py, in the section for their category, and need a test in tests/. Anything tied to one service or one niche workflow belongs in a pack instead. The node API is the same either way: see Build a node pack. A new model from a provider Boltjar already supports needs no code, only a manifest: see Models.

The node reference on this site is written from each node’s declaration: its summary, ports and knobs. Write them for a reader who has never seen the code, since they are what the editor and this site show.

Commit style

The subject reads area: what is true now: lowercase after the colon (node names and proper nouns keep their case), present tense, about 60 characters and 72 at most, no period. area is a part of the project (runtime, editor, server, nodes, models, docs and so on) or a node’s name as the editor shows it (Preview:, Database:). No feat: or fix: prefixes. A body is optional: one to three lines with the symptom and the reason.

editor: a bool knob reads a saved "false" as off

Every commit needs a Signed-off-by: line (git commit -s) for the Developer Certificate of Origin.

Pull requests

1. Fork the repo and branch from main. One topic per pull request.
2. Keep refactors out of feature and fix pull requests.
3. Run the tests above.
4. Open the pull request and fill in the template. Editor changes need a before and after screenshot.
5. CI has to pass. I review every pull request myself, so response times vary.

Contributions come in under the same license they go out: AGPL-3.0-or-later with the node pack exception. There is no CLA, and you keep the copyright on your work.

Conduct and security

Everyone in the project’s spaces follows the Code of Conduct. Found a vulnerability? Report it privately, never in an issue: see Security.