--- url: https://lettuceai.app/docs/sprout title: "Sprout Hardware Probe — LettuceAI" description: "Run Sprout on your Ollama machine so LettuceAI can judge model runnability against that machine's real GPU and memory." --- Menu # Sprout Hardware Probe **Sprout** is a tiny open-source service you run on the machine that hosts your Ollama server. When you browse models in the [Model Browser](/docs/model-browser) with a remote Ollama provider selected, LettuceAI asks Sprout for that machine's real GPU and memory specs, then scores model runnability and recommendations against the hardware that will actually run the model instead of the device you are holding. Why it exists When a model runs on a remote Ollama host, LettuceAI cannot see that host's hardware on its own. Without Sprout, the Model Browser hides runnability badges and recommendations in Ollama mode rather than showing numbers based on the wrong machine. Sprout is a single self-contained binary written in Rust. It does not download, manage, or run models, and it never touches your chats. It answers one question: what GPUs and how much memory does this machine have right now? ## Installing Sprout Grab a prebuilt binary from the [GitHub releases page](https://github.com/LettuceAI/Sprout/releases) for your platform, or build from source with `cargo build --release`. Install it on the machine that runs Ollama, not on the device running LettuceAI. On Linux, the bundled `install.sh` copies the binary to `~/.local/bin` and can register a systemd user service so Sprout starts automatically and restarts on failure: ``` systemctl --user status sprout systemctl --user restart sprout journalctl --user -u sprout -f ``` If the machine should keep serving Sprout while you are logged out, enable lingering once: `sudo loginctl enable-linger $USER` ### First run On first launch, Sprout creates a config file and generates a random 32-character API key, which it prints to the console. Copy that key; LettuceAI will need it. The config file lives at: | Platform | Config path | | --- | --- | | Linux | `~/.config/sprout/config.toml` | | macOS | `~/Library/Application Support/sprout/config.toml` | | Windows | `%APPDATA%\sprout\config.toml` | ## Opening Sprout to your LAN By default Sprout binds to `127.0.0.1:8477`, which means only the machine itself can reach it. Your phone or another computer on the network cannot. To accept LAN connections: 1. Open `config.toml` and change the host line to `host = "0.0.0.0"` 2. Restart Sprout (e.g. `systemctl --user restart sprout`). The config is read once at startup, so edits do nothing until a restart. 3. If the machine runs a firewall, allow inbound TCP on port `8477` 4. From another device, verify with `http://:8477/ping`, which should return a small JSON blob with the Sprout version Keep it on your LAN Sprout only reports hardware specs and requires the API key for those, but there is no rate limiting or IP allowlist. Expose it to your local network, not the open internet. If you need remote access, put it behind a VPN such as WireGuard or Tailscale. ### Configuration reference | Key | Default | What it does | | --- | --- | --- | | host | `127.0.0.1` | Bind address. Use `0.0.0.0` to accept LAN connections. | | port | `8477` | Listen port. | | api\_key | generated | Bearer token clients must send to read specs. Regenerated if left empty. | | require\_auth | `true` | Set to `false` to serve specs without a token. Not recommended. | | tls\_cert\_path / tls\_key\_path | unset | Optional PEM certificate and key. Set both to serve HTTPS instead of HTTP. | ## Connecting from LettuceAI 1. Go to **Settings → Providers** and open your Ollama provider 2. Turn on **Use Sprout for Runnability** 3. Enter the Sprout URL, e.g. `http://192.168.1.10:8477` 4. Paste the API key that Sprout printed on first run into **Sprout API Key** From then on, when that Ollama provider is selected in the Model Browser, runnability badges and hardware recommendations come back and reflect the Ollama machine's GPU and memory. Per-provider setting Sprout is configured on each Ollama provider individually. If you have two Ollama servers on different machines, each one points at the Sprout instance running on its own host. ## How it works Sprout exposes three read-only HTTP endpoints: | Endpoint | Auth | Returns | | --- | --- | --- | | `GET /health` | none | Plain text `ok`, for liveness checks. | | `GET /ping` | none | Service name and version, for discovery. | | `GET /specs` | Bearer token | The full hardware snapshot LettuceAI consumes. | The `/specs` response includes total and available system RAM, CPU name and core count, whether the machine uses unified memory, and one entry per GPU with its vendor, backend (CUDA, Vulkan, or Metal), total and free VRAM, and whether it is a discrete or integrated GPU. NVIDIA cards are read through NVML, AMD and Intel through Vulkan, and Apple GPUs through Metal. LettuceAI validates the payload's `schemaVersion` (currently `1`) before trusting it, then derives the numbers the runnability engine needs: available RAM, the largest pool of free VRAM on a discrete GPU (falling back to integrated GPUs on unified-memory machines), and whether GPU offload is possible at all. Those feed the same scoring used for local models, so the badges mean the same thing everywhere. ### Security model - Only `/specs` requires authentication, and the token check uses a constant-time comparison - The config file is written with owner-only permissions on Unix because it holds the API key - With `tls_cert_path` and `tls_key_path` set, Sprout serves HTTPS. Use a certificate the connecting device trusts, then give LettuceAI an `https://` Sprout URL. ## Troubleshooting - **No runnability badges in Ollama mode**: make sure the toggle is on for the provider you actually selected in the Model Browser, and that the Sprout URL is non-empty. - **"Failed to reach Sprout"**: Sprout is not running, still bound to `127.0.0.1`, or blocked by a firewall. Test `/ping` from the device running LettuceAI. - **401 Unauthorized**: the API key in the provider settings does not match the `api_key` in Sprout's config. - **"Unsupported Sprout schema version"**: the app and Sprout disagree on the payload format. Update whichever side is older. - **Edits not taking effect**: Sprout reads its config only at startup. Restart the service after any change. [ PreviousOllama ](/docs/ollama)[ NextHost API ](/docs/host-api)