Deployment

Troubleshooting? See Troubleshooting for common issues and solutions. Interface Usage? See Interfaces for accessing Telegram, Web API, and CLI.

Quick Start

See Installation for all install methods (Homebrew, one-liner, Docker, manual). The interactive wizard (pnpm wizard) handles all configuration — API keys, interfaces, storage paths, and scheduler. It writes a chmod 0600 .env file and creates the required data directories.

Prerequisites

Node.js 20+, pnpm 9+
Docker and Docker Compose (for Docker deployments)
.env file — generated by pnpm wizard or manually from .env.example

Docker Compose

# Build and start
cd docker
docker compose up -d --build

# View logs
docker compose logs -f echos

# Stop
docker compose down

Services:

redis: Redis 7 for BullMQ job queue (required)
echos: The EchOS application (healthcheck: liveness heartbeat file, independent of ENABLE_WEB — see Troubleshooting)

Data is persisted via volume mounts to ./data/.

With nginx + Let’s Encrypt (HTTPS)

# 1. Generate nginx config from template
sed "s/DOMAIN_NAME/example.com/g" docker/nginx.conf.template > docker/nginx.conf

# 2. Start all services including nginx
cd docker && docker compose --profile nginx up -d

# 3. Obtain SSL certificate
docker compose --profile nginx run --rm certbot certonly \
  --webroot -w /var/www/certbot -d example.com

# 4. Uncomment the HTTPS server block in docker/nginx.conf
# (see the commented block at the bottom of the file)

# 5. Reload nginx
docker compose --profile nginx exec nginx nginx -s reload

Certbot auto-renews every 12 hours.

Manual Deployment

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start (requires Redis running)
pnpm start

Troubleshooting

Module Not Found Errors

If you see Cannot find package '@echos/shared' or '@echos/plugin-youtube' or similar:

# Rebuild all workspace packages
pnpm build

# Or if that fails, clean and rebuild
pnpm clean
pnpm install
pnpm build

LanceDB Native Module Errors

If you see Cannot find module '@lancedb/lancedb-darwin-x64' or similar:

Intel Macs: The project uses LanceDB 0.22.3 (configured in packages/core/package.json)
ARM Macs/Linux: LanceDB should install the correct native binding automatically
Force reinstall: pnpm install --force

Telegram Bot Conflicts

Error: Conflict: terminated by other getUpdates request This means another instance of your bot is already running. Only one instance can poll Telegram. Solution:

# Stop all echos processes
pkill -f "tsx.*index.ts"

# Or find the specific process
ps aux | grep "tsx"
kill <PID>

# Verify nothing is running (should only show "grep echos")
ps aux | grep echos

# Then restart
pnpm start

For production: Use webhooks instead of polling to avoid conflicts.

VPS Deployment (Ubuntu/Debian)

One-liner install

curl -sSL https://raw.githubusercontent.com/albinotonnina/echos/main/install.sh | bash

Installs prerequisites, clones repo, and launches the setup wizard.

systemd service (production)

# /etc/systemd/system/echos.service
[Unit]
Description=EchOS knowledge management
After=network.target

[Service]
Type=simple
User=echos
WorkingDirectory=/home/echos/echos
ExecStart=/usr/local/bin/pnpm start
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now echos
sudo journalctl -u echos -f   # follow logs

SSH / VPS CLI Access

The daemon runs via systemd or Docker as normal. When you SSH in, run queries directly against the live data without interrupting the daemon:

ssh user@your-server
cd ~/echos

# One-shot query
pnpm echos "what are my reminders for this week?"

# Interactive session
pnpm echos

SQLite WAL mode allows concurrent reads (and occasional writes) alongside the running daemon. This is safe for single-user personal use.

Oracle Cloud Deployment

# Deploy to remote server
./scripts/deploy.sh user@your-server-ip

The deploy script:

Syncs project files via rsync
Installs dependencies on remote
Builds the project
Restarts via docker-compose

Important: Dev vs Production

Before starting locally, ensure your production deployment is stopped:

# SSH to production
ssh user@your-server

# Stop the bot
docker compose down
# Or
pkill -f "echos"

# Exit SSH
exit

# Now safe to start locally
pnpm start

Only one instance can poll Telegram at a time. See Troubleshooting for details.

Backup

# Create backup
./scripts/backup.sh ./backups

# Restore (copy files back)
tar -xzf backups/echos_backup_TIMESTAMP.tar.gz

Environment Variables

See .env.example for the full list. Required:

TELEGRAM_BOT_TOKEN - Get from @BotFather on Telegram
ALLOWED_USER_IDS - Comma-separated Telegram user IDs (get from @userinfobot)
At least one LLM key:
- ANTHROPIC_API_KEY - Anthropic pay-as-you-go key from https://console.anthropic.com/
- LLM_API_KEY - API key for any other provider (Groq, Mistral, xAI, etc.)
DEFAULT_MODEL - Model spec: bare ID (claude-haiku-4-5-20251001), provider/model (groq/llama-3.3-70b-versatile), or any ID when using LLM_BASE_URL

Optional:

LLM_BASE_URL - Custom OpenAI-compatible endpoint (e.g. DeepInfra); requires LLM_API_KEY
OPENAI_API_KEY - Required for embeddings and Whisper transcription
WHISPER_LANGUAGE - ISO-639-1 code (e.g. en, fr, de) to pin Whisper transcription language. If unset, Whisper auto-detects. See Troubleshooting.
CACHE_RETENTION - Prompt cache TTL for Anthropic models: long (1h, default), short (5min), none (off). Always none for custom endpoints.
DISABLE_UPDATE_CHECK - Set to true to disable the daily update check. Useful for air-gapped environments with no internet access.
TELEGRAM_REACTIONS - Set to false to disable emoji reactions (👀, 🤗) on incoming Telegram messages. Default: true.

Redis (required):

REDIS_URL - Redis connection URL (default: redis://localhost:6379)

See Scheduler for details.

Process Management

Development

# Start daemon (foreground)
pnpm start

# Stop (Ctrl+C or from another terminal)
pkill -f "tsx.*index.ts"

# CLI — no daemon needed, works alongside or independently
pnpm echos "query"           # one-shot
pnpm echos                   # interactive REPL
echo "msg" | pnpm echos      # pipe mode

Production

For production deployments, use a process manager:

# With PM2
pm2 start "pnpm start" --name echos
pm2 stop echos
pm2 restart echos
pm2 logs echos

# Or use Docker Compose (recommended)
docker compose up -d
docker compose logs -f echos
docker compose stop

Getting Started

Architecture

Features

Operations

Deployment

Deployment

Quick Start

Prerequisites

Docker Compose

With nginx + Let’s Encrypt (HTTPS)

Manual Deployment

Troubleshooting

Module Not Found Errors

LanceDB Native Module Errors

Telegram Bot Conflicts

VPS Deployment (Ubuntu/Debian)

One-liner install

systemd service (production)

SSH / VPS CLI Access

Oracle Cloud Deployment

Important: Dev vs Production

Backup

Environment Variables

Process Management

Development

Production

​Deployment

​Quick Start

​Prerequisites

​Docker Compose

​With nginx + Let’s Encrypt (HTTPS)

​Manual Deployment

​Troubleshooting

​Module Not Found Errors

​LanceDB Native Module Errors

​Telegram Bot Conflicts

​VPS Deployment (Ubuntu/Debian)

​One-liner install

​systemd service (production)

​SSH / VPS CLI Access

​Oracle Cloud Deployment

​Important: Dev vs Production

​Backup

​Environment Variables

​Process Management

​Development

​Production

Deployment

Quick Start

Prerequisites

Docker Compose

With nginx + Let’s Encrypt (HTTPS)

Manual Deployment

Troubleshooting

Module Not Found Errors

LanceDB Native Module Errors

Telegram Bot Conflicts

VPS Deployment (Ubuntu/Debian)

One-liner install

systemd service (production)

SSH / VPS CLI Access

Oracle Cloud Deployment

Important: Dev vs Production

Backup

Environment Variables

Process Management

Development

Production