Skip to main content

​
Installing EchOS

EchOS can be installed in several ways, from a one-line command to manual git clone.

​
One-liner (macOS + Linux)

curl -sSL https://raw.githubusercontent.com/albinotonnina/echos/main/install.sh | bash
This script will:
  1. Install Node.js 20+ via Homebrew / apt / dnf if not present
  2. Install pnpm if not present
  3. Clone the repository
  4. Install dependencies (prebuilt native modules, no C++ toolchain needed)
  5. Build all packages
  6. Launch the setup wizard
Environment overrides:
VariableDefaultDescription
ECHOS_INSTALL_DIR./echosInstallation directory
ECHOS_BRANCHmainGit branch to checkout
ECHOS_NON_INTERACTIVE0Set to 1 to skip the wizard

​
Homebrew (macOS)

brew tap albinotonnina/echos
brew install echos
The formula:
  • Installs Node.js 20 and Redis as dependencies
  • Builds all packages with prebuilt native modules
  • Registers a launchd service for auto-start
After installing: 
echos-setup                # opens browser-based setup wizard
brew services start echos  # start the daemon
echos "search my notes"    # use the CLI

​
Docker

cd docker
docker-compose up -d
Docker handles all dependencies (Node.js, Redis) in containers. See Deployment for full Docker setup.

​
Manual Install

git clone https://github.com/albinotonnina/echos.git && cd echos
pnpm install
pnpm build

​
Setup Wizard

After installation, configure EchOS with one of these methods: 
pnpm wizard
Opens http://localhost:3456 with a guided wizard that walks you through:
  • API keys (Anthropic required, OpenAI optional)
  • Telegram bot configuration
  • Feature toggles (Web UI)
  • Redis connection

​
CLI Setup

pnpm wizard:cli
Interactive terminal wizard with the same configuration steps.

​
Non-interactive Setup

# Set environment variables, then:
pnpm wizard:cli --non-interactive
Reads from environment variables and writes .env without prompts. Useful for CI/automation.

​
Dependencies

​
Required

  • Node.js 20+ — runtime
  • pnpm 10+ — package manager
  • Redis — background scheduler (digests, reminders, cron jobs)

​
What you DON’T need

  • No C++ toolchain — all native modules (better-sqlite3, LanceDB, sharp) ship prebuilt binaries
  • No Python — YouTube transcript extraction uses a pure JavaScript library

​
Native Modules

EchOS uses three native Node.js modules, all with prebuilt binary support:
ModuleUsed ForPrebuilt Strategy
better-sqlite3Metadata databaseprebuild-install (prebuilt binaries for all platforms)
@lancedb/lancedbVector searchPlatform-specific optional deps (@lancedb/lancedb-darwin-arm64, etc.)
sharpImage processingPlatform-specific optional deps (@img/sharp-darwin-arm64, etc.)
No compilation is needed on macOS (ARM64/x64), Linux (x64/ARM64), or Windows.

​
Starting EchOS

# Start the daemon (Telegram + Web interfaces)
pnpm start

# Start with pretty-printed logs
pnpm start | pnpm exec pino-pretty

# Use the CLI (no daemon needed)
pnpm echos "what did I save yesterday?"

​
Updating

# If installed via install.sh or git clone
cd echos
git pull
pnpm install
pnpm build

# If installed via Homebrew
brew upgrade echos

​
Future Distribution Methods

These are planned but not yet implemented:
  • Tauri desktop app — .dmg for macOS with menu bar icon and auto-updates
  • Docker Desktop Extension — one-click install from Docker Hub
  • npm global package — npm install -g echos