Install

Every route ends with the bot running and the web dashboard on http://localhost:3000. The first browser visit creates the dashboard login, unless the installer (or scallopbot web-login) already set one. When you copy .env.example by hand, set one provider key and comment out the placeholder TELEGRAM_BOT_TOKEN line if you are not using Telegram.

Install the dashboard as an app

The web dashboard is a Progressive Web App. In Chrome or Edge use Install app in the address bar; on iPhone or iPad use Share → Add to Home Screen. Browsers only offer this over HTTPS or on localhost. The service worker caches the app shell so it opens offline; chat, memory and API data always come live from your server.

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:

<details> <summary><strong>Alternative: systemd</strong></summary>

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

</details>

Fine-tuned local models (optional)

Two small models fine-tuned for ScallopBot's own jobs are published on Hugging Face: scalloptools-1 (tool selection) and scallopmemory-1 (memory extraction). Both ship as q5 GGUF files (~2.9 GB) that run under Ollama. Plug them in with Multi-Model Mode below (register each as a CUSTOM_PROVIDER_*; point MODEL_FACT_EXTRACTION at scallopmemory-1, and put scalloptools-1 first in PROVIDER_ORDER to make it the chat/tool model). Their benchmark numbers are on scallopbot.com.

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
WEB_UI_ENABLED=true                # Optional: web dashboard + REST/WebSocket API
TELEGRAM_BOT_TOKEN=...             # Optional: enable Telegram
TELEGRAM_ALLOWED_USERS=123456789   # Optional: restrict access
BRAVE_SEARCH_API_KEY=...           # Optional: enable web search

Budget controls:

DAILY_BUDGET=5.00
MONTHLY_BUDGET=100.00
BUDGET_WARNING_THRESHOLD=0.75      # default; dashboard bars turn amber past this

Common options: .env.example; every variable is read in src/config/config.ts.

Add at least one LLM provider API key

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

Requires Node.js 24+.

</details>

CLI Reference

<details> <summary>Show all CLI commands</summary>

</details>

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

OpenClaw column reflects its public README and docs as of October 2026; it ships fast, so corrections are welcome. A fuller write-up is at scallopbot.com/vs/openclaw.