← spectroscope

local setup

This page lists what spectroscope needs on your machine, level by level. Level 1 is all you need to run the app. The levels after it are optional, and one route per level is enough. Mark a step with "I have this" and the ring of its level fills.

0 of 22 steps marked

macOS means Apple silicon. Linux means Debian 12 and 13, Ubuntu 22.04 and 24.04. Windows is not covered. (README.md Apple silicon only, S37, S39, S53, S54)

before you start

Homebrew The macOS commands marked "needs Homebrew" use it, and so does the speech script. If brew is not found, install Homebrew first. Its page shows the install line and explains what it does. The DMG needs no Homebrew. brew.sh (S1, README.md is the same kit without the tap, setup-stt.sh Homebrew missing)

git The commands marked "needs git" clone a repository. To install git, run brew install git, or xcode-select --install for Apple's git in the Command Line Tools. git-scm.com (S48)

git The commands marked "needs git" clone a repository. To install git, run sudo apt-get install git. git-scm.com (S49)

Docker's apt repository The Linux Docker command installs packages from Docker's own apt repository. Add that repository first, with the lines on Docker's install page for your system. Docker on Ubuntu and Docker on Debian (S37, S38, S39)

cmake and a C and C++ compiler The whisper.cpp build lines on Linux call cmake and a C and C++ compiler. Install both from your distribution first. The whisper.cpp README shows the build. whisper.cpp README (S24)

Ollama The Linux line marked "needs Ollama" talks to a running Ollama. Install Ollama first, with its installer or the manual route on its Linux page. Step 2.2 quotes the installer. docs.ollama.com (S12)

level 1

run the app

The app opens and answers.

1.1

install the app

Installs the desktop app. The DMG, the Homebrew cask, the apt package and the AppImage bring their own Java runtime and their own llama-server.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipnot needed forsource build

macOS

Homebrew cask

needs Homebrew

brew install --cask spectroscope/tap/spectroscope

source README.md spectroscope/tap/spectroscope

Apple silicon only. There is no Intel build. (README.md Apple silicon only)

script

mac-step-1-1.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

apt, Debian 12 and Ubuntu 24.04, x86_64

curl -fsSL https://apt.spectroscope.dev/spectroscope.asc | sudo gpg --dearmor -o /usr/share/keyrings/spectroscope.gpg
echo "deb [signed-by=/usr/share/keyrings/spectroscope.gpg] https://apt.spectroscope.dev stable main" | sudo tee /etc/apt/sources.list.d/spectroscope.list
sudo apt update && sudo apt install spectroscope

source README.md apt.spectroscope.dev stable main

script

linux-step-1-1.sh

Scripts are files to download, read and run yourself. The page runs nothing.

The server jar and the CLI zip need a JDK 21 or newer. Step 1.2 covers it. (README.md run them on a JDK 21)

check

The app opens its window.

source SessionsController.java @GetMapping("/api/health")

1.2

a JDK

Java 21 or newer, for the server jar, the CLI zip and a build from source.

install pathsserver jarCLI zipsource buildnot needed forDMGHomebrew caskapt packageAppImage

This step is not needed for the DMG, Homebrew cask, apt package and AppImage. They bring their own Java runtime. (README.md brings its own Java runtime)

macOS

needs Homebrew

brew install openjdk@21

source S4

so the system Java wrappers find it

sudo ln -sfn $HOMEBREW_PREFIX/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

source S4

script

mac-step-1-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

Ubuntu 22.04 and 24.04, Debian 13

sudo apt install openjdk-21-jdk

source S53, S54

Debian 12 has no openjdk-21-jdk. Add the Adoptium apt repository as its installation page shows, then install temurin-21-jdk. (S53, S55)

script

linux-step-1-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

check

spectro doctor

From the CLI zip: the first check names the Java version and passes at 21 or newer.

source DoctorCommand.java 21+ required

1.3

choose a mode

The first start asks which mode to open. learn is the full app, light is the chat with its workspace, sessions and skills.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

check

The question does not come back on the next start.

source firstStart.ts

The mode question on the first start.The mode question on the first start.
The mode question on the first start.

level 2

a local model

One local route answers a prompt without a cloud key. One of the four steps is enough. With the DMG, the cask, the apt package or the AppImage, the first step needs no extra install.

2.1

the built-in model

A model that runs inside the app with nothing else installed. The kits bring the llama-server engine it runs on.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

only for the server jar, the CLI zip and a source build: installs the engine

needs Homebrew

brew install llama.cpp

source S7

script

mac-step-2-1.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

With the server jar or the CLI zip, you supply llama-server yourself. Step 2.4 shows where to get it. (README.md supply yourself)

In the app, open the model chooser and download a model. It lands in ~/.spectro/models. (LocalModelController.java "/api/local-model/download")

check

The model chooser shows the model as downloaded.

source LocalModelController.java "/api/local-model/catalog"

The model chooser of the built-in model.The model chooser of the built-in model.
The model chooser of the built-in model.

qwen3-4b, the default built-in model: 2,497,280,256 bytes. Measured 2026-10-11, method: sizeBytes in the product's model catalogue (models.json "sizeBytes": 2497280256).

2.2

Ollama

A local model server. spectroscope connects to it at http://localhost:11434.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

with Homebrew

needs Homebrew

brew install ollama

source S8

needs Homebrew

brew services start ollama

source S8

the first model

ollama pull qwen2.5:7b

source S10, S14

The Ollama app needs macOS 14 or newer. (S11)

script

mac-step-2-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

This is Ollama's own installer for Linux. It downloads a script and runs it in your shell. Read the script first. The same page shows a manual route that unpacks the program without a script. The vendor page.

curl -fsSL https://ollama.com/install.sh | sh

source S12

the first model, once Ollama runs

needs Ollama

ollama pull qwen2.5:7b

source S10, S14

script

linux-step-2-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

check

ollama -v

Prints the installed version.

source S12

The provider picker with the local routes.The provider picker with the local routes.
The provider picker with the local routes.

Ollama.dmg: 206,944,401 bytes. Measured 2026-10-11, method: content-length of a HEAD request (S66).

qwen2.5:7b: 4.7 GB, 32K context. Measured 2026-10-11, method: read on the Ollama library page (S14).

2.3

LM Studio

A desktop app with a local model server. spectroscope connects to it at http://localhost:1234.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

with Homebrew

needs Homebrew

brew install --cask lm-studio

source S20

after you have downloaded a model in the Discover tab

lms server start

source S16, S18

Apple silicon, macOS 14 or newer, 16 GB of memory or more recommended. (S19)

You can also start the server with the switch in the Developer tab. (S16)

script

mac-step-2-3.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

This step is not covered on Linux yet.

check

curl http://localhost:1234/v1/models

Answers with JSON once the server runs.

source S17

2.4

llama.cpp server

Runs a GGUF model file you choose. spectroscope connects to it at http://localhost:8080.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

needs Homebrew

brew install llama.cpp

source S7, S21

model.gguf stands for your model file

llama-server -m model.gguf --port 8080

source S22

script

mac-step-2-4.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

model.gguf stands for your model file

llama-server -m model.gguf --port 8080

source S22

On Linux, the install page of llama.cpp lists the ways to get llama-server. (S21)

Keep --port 8080. The master branch of llama.cpp listens on 9931 when no port is given; spectroscope looks on 8080. (S22, SpectroConfig.java case "llamacpp" -> "http://localhost:8080")

check

curl http://localhost:8080/health

Answers once the model is loaded.

source DoctorCommand.java case LLAMACPP ->

level 3

speech

The microphone button turns speech into text on this machine, or through a hosted key.

3.2

whisper-cli

Turns the microphone recording into text on this machine.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

needs Homebrew

brew install whisper-cpp

source S5, S6, SttController.java "brew install whisper-cpp"

whisper-cpp is the old name of the Homebrew formula whisper.cpp. Homebrew resolves it. (S5)

script

mac-step-3-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

needs git

git clone https://github.com/ggml-org/whisper.cpp.git

source S24

cd whisper.cpp

source S24

needs cmake and a C and C++ compiler

cmake -B build

source S24

needs cmake and a C and C++ compiler

cmake --build build -j --config Release

source S24

Then put build/bin/whisper-cli on the PATH. (SttController.java build/bin/whisper-cli on the PATH)

script

linux-step-3-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

check

brew info whisper-cpp

Shows whisper.cpp as installed.

source S6

The app's speech status lists whisper-cli as found.

source SttController.java @GetMapping("/api/stt/status")

Screenshot to come: voice-notice
The notice on the first press of the microphone button.
3.3

speech model

The model file whisper-cli reads: ggml-small.bin in ~/.spectro/models.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

in the folder you downloaded the script to

needs Homebrew

bash setup-stt.sh

source setup-stt.sh

On macOS the script also installs whisper-cpp with Homebrew when it is missing. (setup-stt.sh command -v whisper-cli)

script

setup-stt.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

in the folder you downloaded the script to

bash setup-stt.sh

source setup-stt.sh

script

setup-stt.sh

Scripts are files to download, read and run yourself. The page runs nothing.

The script downloads the model and checks its sha256. The app can also download this file from Settings, and it checks the same sha256. (setup-stt.sh sha256_of)

check

ls -l ~/.spectro/models/ggml-small.bin

The file has 487,601,967 bytes.

source SttController.java ".spectro", "models", S28

ggml-small.bin: 487,601,967 bytes. Measured 2026-10-11, method: Hugging Face model tree API (S28).

3.4

hosted speech

Sends speech to a hosted service instead of a local model, when a key is present.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

Set OPENAI_API_KEY in the environment, or type the key in Settings. This page never shows a key. (HostedTranscriber.java KEY_ENV = "OPENAI_API_KEY")

check

The app's speech status reports a hosted key as present.

source SttController.java @GetMapping("/api/stt/status")

3.5

CLI voice

The CLI's /voice records with ffmpeg, and --speak reads answers aloud with Piper. The app does not need either.

install pathsCLI zipsource buildnot needed forDMGHomebrew caskapt packageAppImageserver jar

macOS

needs Homebrew

brew install ffmpeg

source S56

Piper and its voice, in the folder you downloaded the script to

bash setup-tts.sh

source setup-tts.sh

script

setup-tts.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

Piper and its voice, in the folder you downloaded the script to

bash setup-tts.sh

source setup-tts.sh

Playback uses aplay, or ffplay when aplay is missing. (PiperSpeechEngine.java else aplay, else ffplay)

script

setup-tts.sh

Scripts are files to download, read and run yourself. The page runs nothing.

check

ls ~/.spectro/models/piper/piper ~/.spectro/models/en_US-lessac-medium.onnx

Both files are listed.

source DoctorCommand.java resolve("piper")

Piper for macOS on Apple silicon: 19,146,957 bytes. Measured 2026-10-11, method: content-length of a HEAD request (S64).

Piper for Linux x86_64: 26,460,462 bytes. Measured 2026-10-11, method: content-length of a HEAD request (S64).

The voice en_US-lessac-medium: 63,201,294 bytes. Measured 2026-10-11, method: Hugging Face model tree API (S65).

level 4

web search

The web_search tool uses a private SearXNG instance that answers JSON, or a Tavily or Brave key.

4.1

Docker

Runs the SearXNG container of the next step.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

Docker Desktop with Homebrew

needs Homebrew

brew install --cask docker-desktop

source S35

or OrbStack, which also runs Docker

needs Homebrew

brew install orbstack

source S36

Open Docker Desktop once and accept its agreement. It needs macOS 14 or newer and at least 4 GB of memory. (S34, S35)

script

mac-step-4-1.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

after you have added Docker's apt repository

needs Docker's apt repository

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

source S37, S39

On Linux, docker needs sudo until you have done Docker's post-installation steps. Docker's install page links them. (S37)

script

linux-step-4-1.sh

Scripts are files to download, read and run yourself. The page runs nothing.

check

The app's Docker status reads ready.

source DockerStatusController.java "/api/docker/status"

sudo docker run hello-world

Runs the hello-world image.

source S37

Screenshot to come: web-search-settings
Settings, web search, with the Docker state.

Docker.dmg for Apple silicon: 587,631,519 bytes. Measured 2026-10-11, method: content-length of a HEAD request (S67).

4.2

SearXNG

A private search engine in Docker that answers JSON. The script writes its address to ~/.spectro/.env.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

make a folder for the script and the files it writes

mkdir -p ~/spectro-searxng && cd ~/spectro-searxng

source webSearchSetup.ts SEARXNG_FOLDER = "~/spectro-searxng"

save install-searxng.sh into that folder, read it, then run this there

bash install-searxng.sh

source install.sh

script

install-searxng.shdocker-compose.yml

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

make a folder for the script and the files it writes

mkdir -p ~/spectro-searxng && cd ~/spectro-searxng

source webSearchSetup.ts SEARXNG_FOLDER = "~/spectro-searxng"

save install-searxng.sh into that folder, read it, then run this there

bash install-searxng.sh

source install.sh

install-searxng.sh calls docker without sudo. On Linux, do Docker's post-installation steps from step 4.1 first, or the script stops at a permission error. (S37, install.sh --project-directory "$state_dir" up -d)

script

install-searxng.shdocker-compose.yml

Scripts are files to download, read and run yourself. The page runs nothing.

The script needs openssl. It writes settings.yml with JSON switched on, starts one container, waits for a JSON answer, and only then writes SPECTRO_SEARXNG_URL. (install.sh It does exactly three things)

install-searxng.sh runs on its own. If there is no docker-compose.yml in its folder, it writes one with the same content as the docker-compose.yml on this page. The app offers the same script in Settings, under web search. (install.sh none was beside this script, webSearchSetup.ts SEARXNG_SCRIPT_ROUTE)

check

curl 'http://localhost:8888/search?q=test&format=json'

Answers JSON. A 403 means json is missing under search.formats; web_search then reads the HTML page and still answers.

source S31, install.sh SEARXNG_PORT:-8888

4.3

confirm the tier

Shows which search route web_search takes.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

check

spectro doctor

The web search line starts with searxng and names the address.

source DoctorCommand.java "web search: ", WebSearchTiers.java case SEARXNG ->

4.4

Tavily or Brave

A hosted search key instead of SearXNG.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

Create a key with Tavily or Brave and type it in Settings. The variables are TAVILY_API_KEY and BRAVE_API_KEY. With both keys, web_search uses Tavily. A saved SearXNG address comes before both. (WebSearchTiers.java TAVILY_KEY_ENV = "TAVILY_API_KEY")

check

spectro doctor

The web search line names the Tavily or the Brave Search API.

source DoctorCommand.java "web search: "

level 5

code graph

Build code graph works, and the browse_page tool finds a browser.

5.1

uv

Installs graphify in the next step.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

This is uv's own installer. It downloads a script and runs it in your shell. Read the script first. The vendor page.

curl -LsSf https://astral.sh/uv/install.sh | sh

source S41

needs Homebrew

brew install uv

source S41, S42

script

mac-step-5-1.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

This is uv's own installer. It downloads a script and runs it in your shell. Read the script first. The same page lists other routes. The vendor page.

curl -LsSf https://astral.sh/uv/install.sh | sh

source S41

check

The uv command of the next step runs.

source S41

5.2

graphify

Makes the Build code graph button work. The package is graphifyy with two y; the command it installs is graphify.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

uv tool install graphifyy

source S43, GraphifyCommand.java INSTALL_LINE

only when graphify is not found afterwards

uv tool update-shell

source S43

script

mac-step-5-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

Linux

uv tool install graphifyy

source S43, GraphifyCommand.java INSTALL_LINE

only when graphify is not found afterwards

uv tool update-shell

source S43

script

linux-step-5-2.sh

Scripts are files to download, read and run yourself. The page runs nothing.

check

spectro doctor

The code graph line names the graphify path.

source DoctorCommand.java code graph: graphify at

Screenshot to come: codegraph-chip
The Build code graph chip.
5.3

a browser

The browse_page tool reads web pages through Chrome or another Chromium browser.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

macOS

Install Google Chrome. Chromium, Microsoft Edge or Brave in /Applications also count, and SPECTRO_CHROME can point at another binary. (BrowsePageTool.java Google Chrome.app)

Linux

Install Chrome or Chromium. The tool looks for google-chrome, google-chrome-stable, chromium, chromium-browser or chrome on the PATH, and SPECTRO_CHROME can point at another binary. (BrowsePageTool.java PATH_BINARIES)

check

spectro doctor

The browse_page line names the browser it found.

source DoctorCommand.java browse_page: chrome at

level 6

playbooks

A playbook runs from start to end on the models it names.

6.1

the spectro playbook

The playbook that ships with the app, with its skills and templates. You copy it in the app; there is nothing to download.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

check

The playbook list shows spectro.

source PlaybookController.java @GetMapping("/api/playbooks")

6.3

model slots

Each of the playbook's four model slots has a model that answers. The fast slot names the Ollama tag qwen3.5:27b-q4_K_M; the other three need an Anthropic key.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

check

The start preview shows ready for all four slots.

source PlaybookController.java "/api/playbooks/start-preview"

qwen3.5:27b-q4_K_M: 17 GB, 256K context. Measured 2026-10-11, method: read on the Ollama library page (S62).

level 7

developer path

Your project folder is the workspace, and the playbook's checks can run its tests.

7.1

workspace

Point the app at your project folder.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

check

The folder chip in the header shows the project folder.

source SpectroConfig.java String workspace,

7.2

test command

The playbook's tests_green check runs the command you give for {test}.

install pathsDMGHomebrew caskapt packageAppImageserver jarCLI zipsource build

check

The start preview shows {test} as filled.

source playbook.json "tests_green"