> ## Documentation Index
> Fetch the complete documentation index at: https://docs.echos.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> How to install and update EchOS — one-liner, Homebrew, Docker, or manual setup.

# Installing EchOS

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

***

## Quick Install (Recommended)

### One-liner (macOS + Linux)

```bash theme={null}
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:**

| Variable                | Default   | Description                   |
| ----------------------- | --------- | ----------------------------- |
| `ECHOS_INSTALL_DIR`     | `./echos` | Installation directory        |
| `ECHOS_BRANCH`          | `main`    | Git branch to checkout        |
| `ECHOS_NON_INTERACTIVE` | `0`       | Set to `1` to skip the wizard |

***

### Homebrew (macOS)

```bash theme={null}
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:

```bash theme={null}
echos-setup                # opens browser-based setup wizard
brew services start echos  # start the daemon
echos "search my notes"    # use the CLI
```

***

### Docker

```bash theme={null}
cd docker
docker compose up -d
```

Docker handles all dependencies (Node.js, Redis) in containers. See [Deployment](https://docs.echos.sh/deployment) for full Docker setup.

***

## Manual Install

```bash theme={null}
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:

### Browser-based Setup (Recommended)

```bash theme={null}
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

```bash theme={null}
pnpm wizard:cli
```

Interactive terminal wizard with the same configuration steps.

### Non-interactive Setup

```bash theme={null}
# 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:

| Module             | Used For          | Prebuilt Strategy                                                       |
| ------------------ | ----------------- | ----------------------------------------------------------------------- |
| `better-sqlite3`   | Metadata database | `prebuild-install` (prebuilt binaries for all platforms)                |
| `@lancedb/lancedb` | Vector search     | Platform-specific optional deps (`@lancedb/lancedb-darwin-arm64`, etc.) |
| `sharp`            | Image processing  | Platform-specific optional deps (`@img/sharp-darwin-arm64`, etc.)       |

No compilation is needed on macOS (ARM64/x64), Linux (x64/ARM64), or Windows.

***

## Starting EchOS

```bash theme={null}
# 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?"
```

***

## Stopping EchOS

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={null}
    brew services stop echos

    # Restart
    brew services restart echos

    # Check status
    brew services info echos
    ```
  </Tab>

  <Tab title="Manual / Source">
    ```bash theme={null}
    # If running in foreground, press Ctrl+C

    # If running via pm2
    pm2 stop echos
    pm2 restart echos
    ```
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    cd docker
    docker compose stop      # stop
    docker compose restart   # restart
    ```
  </Tab>
</Tabs>

***

## Updating

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={null}
    brew update
    brew upgrade echos
    ```

    Homebrew handles the full cycle — pulls the new version, rebuilds, and restarts the service if it was running.

    ```bash theme={null}
    # Verify the new version
    echos --version

    # Restart if needed
    brew services restart echos
    ```
  </Tab>

  <Tab title="Source (git clone / install.sh)">
    Stop EchOS before updating, then pull and rebuild:

    ```bash theme={null}
    cd echos

    # Stop the running daemon first
    # (Ctrl+C if foreground, or pm2 stop echos, or systemctl stop echos)

    git pull
    pnpm install
    pnpm build

    # Restart
    pnpm start
    ```

    <Warning>
      Always run `pnpm install` after pulling — new versions may add or update dependencies.
    </Warning>
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    cd echos
    git pull
    cd docker
    docker compose down
    docker compose up -d --build
    ```

    The `--build` flag ensures the image is rebuilt with the latest code.
  </Tab>
</Tabs>

### Checking your version

```bash theme={null}
# CLI
echos --version

# Or from the repo (from the EchOS repo root)
cd echos          # or the path to your cloned repo
git fetch --tags  # ensure tags are available locally
git describe --tags --abbrev=0
```

See [Releases](https://github.com/albinotonnina/echos/releases) for changelogs.

***

## 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`