SuperBrain Server Installer & CLI

1.0.60 · active · verified Sun Apr 19

SuperBrain Server is an npm package acting as a command-line interface (CLI) wrapper for installing, configuring, and managing the SuperBrain Python backend. As of version 1.0.60, it provides a one-line setup for a self-hosted AI-powered second brain designed for Android devices, facilitating the analysis and organization of content from platforms like Instagram, YouTube, and the web. Its core functionalities include a multi-provider AI router for services like Groq, Gemini, OpenRouter, and Ollama, automatic background music identification via Shazam, and audio transcription using Groq Whisper with a local OpenAI Whisper fallback. The package simplifies the deployment process, handling Python virtual environment creation and dependency installation, and offers commands for status checking, updates, and network configuration (e.g., Ngrok). While specific release cadence is not explicitly stated, updates align with new features and improvements to the SuperBrain ecosystem, providing a robust, locally controlled alternative to cloud-based 'second brain' solutions.

Common errors

```
python: command not found
```
cause Python 3.10+ is not installed or is not accessible in the system's PATH environment variable.

fix Install Python 3.10+ from python.org and ensure it's added to your system's PATH during installation, or manually add it.
```
Backend Not Reachable from Phone (user reported symptom)
```
cause The mobile device is on a different network than the server, or network firewall rules are blocking access to the server's port (default 5000).

fix If on a different network, use `ngrok http 5000` to expose the server publicly. If on the same network, check local firewall settings to ensure port 5000 is open.

Warnings

gotcha The SuperBrain Server backend requires specific external system dependencies (Node.js 20+, Python 3.10+, and ffmpeg) to be pre-installed and available in the system's PATH. Failure to meet these requirements will prevent the backend from installing or running correctly.
Fix: Ensure Node.js version 20 or higher, Python version 3.10 or higher, and ffmpeg are installed and correctly configured in your system's environment variables before running `superbrain-server`.
gotcha The initial run of `superbrain-server` (especially the first time on a new system) involves extensive setup, including unpacking files, creating a Python virtual environment, installing numerous Python dependencies, and an interactive configuration process for AI keys. This can take significant time and requires user interaction.
Fix: Allocate sufficient time for the first-time setup to complete, which may take several minutes. Be prepared to enter required API keys (e.g., for Groq, Gemini) during the interactive setup prompts.
gotcha The SuperBrain backend, along with its configuration and data, is permanently installed in a hidden directory within the user's home directory (`~/.superbrain-server` on macOS/Linux or `%USERPROFILE%\.superbrain-server` on Windows). Users should be aware of this location for troubleshooting, manual updates, or data management.
Fix: For advanced troubleshooting or direct access to backend files, navigate to `~/.superbrain-server` (Linux/macOS) or `%USERPROFILE%\.superbrain-server` (Windows).
gotcha After the SuperBrain backend server starts, connecting the Android mobile app requires manually copying the server's IP/URL and a generated 'Access Token' from the backend console into the app's settings. Incorrect configuration will prevent the app from connecting to your self-hosted server.
Fix: Carefully copy the full server address (IP/URL) and the Access Token displayed in the terminal after the server starts, then paste them accurately into the SuperBrain Android app's 'Server IP/URL' and 'Access Token' fields under settings.
gotcha If your mobile device is not on the same local network as your SuperBrain server, the app will be unable to reach the backend directly. This typically requires exposing the local server to the internet via a tunneling service.
Fix: Use a tunneling service like Ngrok (e.g., `ngrok http 5000` if your server runs on port 5000) to create a publicly accessible URL for your backend. Use the generated HTTPS URL in your SuperBrain mobile app's settings.

Install

npm install superbrain-server npm
yarn add superbrain-server yarn
pnpm add superbrain-server pnpm

Imports

superbrain-server
wrong:
```
import superbrainServer from 'superbrain-server';
```
correct:
```
npx -y superbrain-server@latest
```
This package is a CLI wrapper for a Python backend. Its primary use is via command-line execution, not programmatic JavaScript imports. The `npx` command executes the latest version without global installation, handling all setup on first run.
superbrain-server status
wrong:
```
import { status } from 'superbrain-server';
```
correct:
```
npx -y superbrain-server@latest status
```
Subcommands extend the core CLI functionality. If the package is globally installed via `npm install -g superbrain-server`, you can omit `npx -y` and simply run `superbrain-server status`.
superbrain-server update
wrong:
```
require('superbrain-server').updateBackend();
```
correct:
```
npx -y superbrain-server@latest update
```
This command updates the installed Python backend components and dependencies managed by the wrapper. It is executed via the CLI, similar to other subcommands.

Quickstart

Initializes and runs the SuperBrain Python backend, performing all necessary system setup, Python environment creation, dependency installation, and interactive configuration for AI keys and other settings on the first execution.

npx -y superbrain-server@latest

view raw JSON →