Set up BrainBox for your machine.

Models, files, processing, and maintenance.

The models in your workspace

Different models do different jobs. These are the current desk profile defaults; your installed profile and runtime determine what actually runs.

Answers · gemma4:e4b: Google’s Gemma 4 runs through Ollama. BrainBox retrieves relevant passages and provides them as context for the answer. This is the desk answer model; it is not fine-tuned on your imported documents. Model details.
Search · nomic-embed-text: Nomic’s embedding model runs through Ollama and turns text into numerical representations for similarity search. The current library initialization uses 768 dimensions. It retrieves related text; it does not write chat answers. Model details.
Images, optional · qwen3-vl:8b: The desk profile uses Qwen3-VL through Ollama to describe images. Descriptions can become searchable text. Check them against the originals. This does not automatically provide scanned-PDF OCR. Model details.
Audio, optional · Whisper base.en: whisper.cpp uses ggml-base.en.bin to transcribe English audio into text. The transcript can then be indexed. Other languages require a suitable transcription model and configuration. Model files.

Ollama runs models. gbrain stores and searches the library. BrainBox connects retrieval, answer generation, sources, skills, and feedback in the web interface. The model weights, runtime, and harness are separate components with their own licenses.

From a document to a useful answer

Read the information. Import extracts text; optional tools transcribe audio or describe images.
Index the text. gbrain stores the content and builds embeddings for semantic retrieval.
Find the context. Search retrieves passages relevant to the question, including text with related meaning.
Write with sources. The answer model uses retrieved context to compose an answer. Open the citations and check the original.

Embeddings are an index, not a replacement for your files or a guarantee that the answer is correct. Keep the source documents and review important outputs.

Changing the embedding model

Use the same embedding model and dimensions for indexed text and queries. Downloading a different model or editing models.embed does not migrate an existing index. Back up the library, choose supported dimensions, rebuild embeddings, and verify retrieval before switching. Current initialization pins 768 dimensions, so a model with a different output size needs a configuration/code migration. Do not mix vectors from different models, even if their dimensions match. Get help with a migration.

Choose an answer model

Open Local setup in the app. The list comes from the models installed in your configured runtime. Selecting a model saves it for future answers; it does not download one.

For Ollama setups, these commands inspect the runtime and download the default desk answer model:

ollama list
ollama pull gemma4:e4b

Model size affects memory use and answer speed. Start with a model your machine can comfortably run. The Gemma, Qwen, GLM, and Nemotron names on the site describe model families, not a guarantee that every model works on every device.

Search uses a separate embedding model. Do not change its dimensions or replace it in an existing library without a migration and re-indexing plan. Ask AIsoft to help with this change.

Not sure which models fit your machine and workflow? Help me set up ↗

Know what your settings control

The installer creates ~/BrainBox/myworkspace/brainbox.yaml. Restart the service after editing that file. Environment variables can override it. A model selected in the app is saved separately in preferences.json and takes precedence during answer generation.

profile: desk
policy: local_only
models:
  chat: gemma4:e4b
  embed: nomic-embed-text
bind: 127.0.0.1
port: 8630

This is the core of the desk configuration, not a replacement for the complete file supplied by the installer. Keep its audio and image settings if you use those features.

Choose Automatic selection in the app to return to configured model selection. Skills and feedback stay scoped to the current library.

Add audio and image support

Audio uses whisper.cpp and a downloaded transcription model. Image descriptions use a local vision model through Ollama. The full Mac installer sets up these optional dependencies; rerun the supplied installer without the opt-out flags to add them.

Open Local setup to check the tools. Try one short recording or image before importing a large collection. Image descriptions are model-generated text and should be checked against the original. Image support does not make scanned-PDF OCR available.

If your configuration explicitly disables audio or vision, installing a model alone does not enable that feature. Review the modalities settings with AIsoft.

Other local runtimes and devices

The backend can use an OpenAI-compatible model server with engine: openai and engine_url. This path has been checked against Ollama’s compatible API. Other servers need their own validation; an API-compatible interface does not establish hardware support.

Mac, Windows, Linux, AMD systems, Raspberry Pi, and DGX machines have different model and runtime requirements. See Linux status and Windows status. Neither has a verified BrainBox installation path. Ask for a machine-specific setup before buying hardware or choosing a large model.

Use another device

A phone or second computer can use a browser while one configured machine runs BrainBox and its models. It does not need a separate model installation.

The default desk setup accepts connections only from the host computer. Remote access needs a private-network setup and a review of who can reach it. BrainBox does not yet provide a multi-user sign-in system. Do not expose its port to the public internet.

Tailscale and field profiles exist for assisted setups. The field profile listens on network interfaces and does not create a hotspot by itself. Leave the default desk binding in place until your network has been configured deliberately.

Back up, update, and recover

Wait for imports and answers to finish. On a Mac installed with the pilot installer, stop the login service before backing up so the database is at rest:

launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/us.aisoft.brainbox.plist"
bash "$HOME/BrainBox/app/scripts/backup.sh" myworkspace

If you started BrainBox manually, stop that Terminal process instead. The backup script writes an archive and checksum in ~/BrainBox-backups. Store a copy somewhere safe; the archive contains your documents and saved workspace data.

To resume the Mac login service:

launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/us.aisoft.brainbox.plist"

For an update, back up first, then run the installer from the new AIsoft-supplied bundle using the same client name. Reopen localhost:8630/app and verify a known document and source link.

For recovery, keep the current library intact and ask AIsoft to help verify the checksum and restore to a separate location first. Avoid extracting a backup over a running library.

Remove the app

The following command is for the Mac installer only. On Linux/WSL, stop the manual process and remove the extracted app folder when you no longer need it; keep the separate library and model files until you have a verified backup.

bash "$HOME/BrainBox/app/install.sh" --uninstall

This removes the installed app and its login services. Library folders and downloaded models remain. Removing those is a separate decision; keep a verified backup first.