Deployment

See the full deployment guide or the Raspberry Pi notes for backup, isolation, rollback and security guidance. Keep production credentials and operator-specific details in a private runbook outside the repository.

One-Command Server Setup (Ubuntu 24.04)

git clone https://github.com/tashfeenahmed/scallopbot.git /opt/scallopbot
cd /opt/scallopbot
bash scripts/server-install.sh    # Installs Node 24, PM2, voice deps, Ollama
cp .env.example .env && nano .env
pm2 start ecosystem.config.cjs --env production && pm2 save

The install script is idempotent and sets up:

Quick Start

```bash git clone https://github.com/tashfeenahmed/scallopbot.git cd scallopbot npm install

cp .env.example .env

Multi-Model Mode (optional)

One model serves every purpose by default. If you want specialized models — say, a fine-tuned 4B for memory operations and a different model for the main agent loop — toggle multi-model mode on and register any OpenAI-compatible endpoint under your own name:

```bash MULTI_MODEL_ENABLED=true CUSTOM_PROVIDER_MY_TOOLS=http://localhost:11434/v1|my-tools-model CUSTOM_PROVIDER_MY_MEMORY=http://localhost:11434/v1|my-memory-model

Optional exact token limits for custom/local models

MODEL_TOKEN_LIMITS='{"my_memory":{"contextWindowTokens":262144,"maxOutputTokens":32768}}'

Optional pricing for paid custom endpoints; local/free custom endpoints stay $0

COST_MODEL_PRICING='{"my_tools/my-tools-model":{"inputPerMillion":0.3,"outputPerMillion":1.8}}'

Lifecycle Event Relay (optional)

Set SCALLOPBOT_EVENT_WEBHOOK_URL to emit key lifecycle events to an external orchestrator:

SCALLOPBOT_EVENT_WEBHOOK_URL=https://orchestrator.example.com/scallopbot/events
SCALLOPBOT_EVENT_WEBHOOK_SECRET=replace-with-shared-secret
SCALLOPBOT_AGENT_ID=scallopbot

The webhook receives POST payloads for memory.consolidation_complete, memory.reflection_output, and session.affect_change. If a secret is set, it is sent as a bearer token.

Configuration

Minimal .env:

ANTHROPIC_API_KEY=sk-...           # At least one provider required
TELEGRAM_BOT_TOKEN=...             # Optional: enable Telegram
TELEGRAM_ALLOWED_USERS=123456789   # Optional: restrict access
BRAVE_SEARCH_API_KEY=...           # Optional: enable web search

Budget controls:

COST_DAILY_BUDGET=5.00
COST_MONTHLY_BUDGET=100.00
COST_WARNING_THRESHOLD=0.8

Full reference: .env.example

Add at least one LLM provider API key

npm run build node dist/cli.js start ```

Requires Node.js 24+.

CLI Reference

Local-First Voice Pipeline

Speech-to-text via faster-whisper (CTranslate2-optimized Whisper) and text-to-speech via Kokoro (82M param ONNX model) run entirely on-device with zero API cost. Cloud providers (Groq STT, OpenAI TTS) serve as automatic fallbacks. Telegram voice messages are transcribed inline; voice replies are synthesized when enabled.

Comparison with OpenClaw

Alternative: systemd

sudo tee /etc/systemd/system/scallopbot.service << EOF
[Unit]
Description=ScallopBot AI Assistant
After=network.target

[Service]
Type=simple
User=scallopbot
Group=scallopbot
WorkingDirectory=/opt/scallopbot
EnvironmentFile=/opt/scallopbot/.env
ExecStart=/usr/bin/node /opt/scallopbot/dist/cli.js start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now scallopbot