Install

Boltjar runs on Windows, macOS and Linux. There is no installer: you get the folder, run one script, and open a link.

Before you start

• Node.js 18 or newer (nodejs.org). The first start builds the editor, and that needs Node. Later starts skip the build.
• Python 3.11, 3.12 or 3.13, if you have one. If none is installed, the start script downloads a portable Python 3.12 into .python/ and checks it against the release’s SHA-256 sums before it uses it.
• Git, if you want to clone. A ZIP works just as well.

1. Get the code

git clone https://github.com/Boltjar/Boltjar.git
cd Boltjar

Or download the ZIP and unpack it where you want Boltjar to live.

2. Start it

Windows: double-click start.bat, or run it from a terminal in the folder.

macOS and Linux:

./start.sh

The script creates .venv, installs requirements.txt (and again only when that file changes), builds the editor when it is missing, then starts the server.

3. Open the editor

The script prints the address, and opens it in your browser when it runs on a local screen:

http://127.0.0.1:8770

The chat example opens first. Press On at the top and type into the Chat Input node. Its LLM node has no model picked, so it answers with the offline mock: a reply that starts with [mock] and repeats the start of its prompt, and you can see the graph work before anything else. For a real reply, pick a model on that LLM node (connect a provider first in Settings › AI Providers). Its voice nodes ship switched off; pick a voice model on the TTS node and switch them on to hear each reply.

To stop Boltjar, press Ctrl+C in the window the script opened. Every running graph is turned off on the way out.

Connect a model

Local models with Ollama

Install Ollama, then pull a model. From a terminal:

ollama pull gemma4:e4b

Or open Settings › AI Providers from the gear in the top bar: the Ollama card lists the models you have, pulls new ones with a progress bar, and removes them. Ollama needs no key. Boltjar looks for it at http://localhost:11434; set OLLAMA_BASE_URL in .env to use another address. The models you pull show up in the model pickers on their own. A graph keeps the model its LLM node names; pick an Ollama model there to run on it.

Cloud models and voices

Open Settings › AI Providers, go to AI Providers, and paste a key. Or copy .env.example to .env and fill in the keys you have. For example:

Key	What it turns on
XAI_API_KEY	Grok chat models, xAI voices (TTS) and transcription (STT)
ANTHROPIC_API_KEY	Claude models
OPENAI_API_KEY	OpenAI chat models
FISH_API_KEY	Fish Audio voices and transcription
ELEVENLABS_API_KEY	ElevenLabs voices and transcription

The models a key reaches show up in the pickers on their own. A cloud chat model without its key answers with the mock reply, and a voice node without its key fails with an error that names the key.

Any OpenAI-compatible server

OpenRouter, Groq, LM Studio, llama.cpp, vLLM and other servers that speak OpenAI’s API connect as an endpoint: in Settings › AI Providers, press Add endpoint on the OpenAI-compatible card and give it a name, its base URL and, when it wants one, a key. Models has the details, and says how the model list is read live.

Start options

Arguments given to the start script pass through to python -m boltjar serve, for example start.bat --port 8771 --no-browser:

Option	What it does
--port 8771	Listen on another port. The default is 8770.
--no-browser	Do not open the editor in a browser.
--verbose	Also print the web server’s own lines, every request and full tracebacks.
--host 0.0.0.0 --allow-remote	Listen where other machines can reach it. Any address but this machine’s is refused without --allow-remote. Read Security first.

Update

In a git clone, update.bat or ./update.sh pulls the latest code (fast-forward only), rebuilds the editor when it changed, and starts Boltjar. Your graphs, stores and keys live in user/, which git ignores, so an update leaves them alone.

A ZIP install cannot pull. Download the new ZIP, unpack it, and move your user/ folder (and .env, if you made one) into it.

Manual setup

With Python 3.11 to 3.13 and Node.js 18 or newer installed, this is what the start script does:

# Windows
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
npm ci --prefix editor
npm run build --prefix editor
.\.venv\Scripts\python.exe -m boltjar serve

# macOS and Linux
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
npm ci --prefix editor
npm run build --prefix editor
.venv/bin/python -m boltjar serve

python -m boltjar run examples/demo.json 6 runs a graph without the editor for 6 seconds and prints every live event.

Coming soon

A one-line installer. Until it lands, the three steps above are the way in.

Troubleshooting

• The port is taken. Another program uses 8770. Start with --port 8771 (or any free port).
• The start script says .venv was made on another system. The folder came from another computer or OS. Delete .venv and start again; the script builds a new one.
• The editor page is missing. The first start could not build it, usually because Node.js is not installed. Install Node.js 18 or newer and start again.
• Removing Boltjar. Everything lives in its folder, the portable Python included. Delete the folder. Ollama, if you installed it, is a separate app.