How to Set Up CloddsBot for Self-Hosting: Complete Installation Guide

You can set up CloddsBot for self-hosting by installing Node.js 22+, running npm install -g from the latest release or cloning the repository, configuring your ANTHROPIC_API_KEY environment variable, and launching the gateway with clodds start or Docker.

CloddsBot is an open-source, AI-driven trading terminal that connects to messaging platforms and prediction markets. Unlike managed services, this self-hosted solution stores all state locally in an SQLite database under ~/.clodds and executes trades through a TypeScript-based gateway architecture. The source code in alsk1992/CloddsBot provides four distinct installation paths, from a global npm install to Docker Compose orchestration defined in docker-compose.yml.

Prerequisites for Self-Hosting

Before you set up CloddsBot for self-hosting, ensure your environment meets these minimum requirements:

• Node.js 22+ – Required to run the gateway, AI agents, and CLI tooling.
• Python 3.x – Necessary for trading scripts such as the Bittensor side-car.
• SQLite – Bundled with the application for persistent storage of users, sessions, and trades.
• Docker (optional) – Required only if you choose containerized deployment.
• API Keys – At minimum, an ANTHROPIC_API_KEY is required; optional keys include TELEGRAM_BOT_TOKEN or WEBCHAT_TOKEN for channel integrations.

Installation Methods

You can install CloddsBot via four different methods depending on your infrastructure preferences. All methods ultimately deploy the same src/gateway/index.ts orchestration layer.

Quick Global Install

The fastest way to set up CloddsBot for self-hosting uses the pre-built npm package and interactive wizard:

npm install -g https://github.com/alsk1992/CloddsBot/releases/latest/download/clodds.tgz
clodds onboard

The onboard command prompts for your Anthropic API key, lets you select a messaging channel, writes the configuration to ~/.clodds/.env, and optionally starts the gateway immediately.

Build from Source

For developers who need to modify the channel adapters or trading logic in src/agents/main-agent.ts, build from the GitHub repository:

git clone https://github.com/alsk1992/CloddsBot.git
cd CloddsBot
npm ci
cp .env.example .env

# Edit .env with your API keys

npm run build
npm start

This compiles TypeScript to ./dist and launches the gateway using the source entry point at src/gateway/index.ts.

Docker Single Container

Deploy CloddsBot as a single container for simplified dependency management:

docker build -t clodds .
docker run --rm -p 18789:18789 \
  -e ANTHROPIC_API_KEY=your_key_here \
  -e TELEGRAM_BOT_TOKEN=your_token_here \
  -v clodds_data:/data clodds

Inside the container, the CLODDS_STATE_DIR environment variable is set to /data, ensuring the SQLite database persists at /data/clodds.db across restarts.

Docker Compose Multi-Service

For production environments requiring persistent volumes and easier secret management, use the provided docker-compose.yml:

# After cloning the repository

docker compose up -d --build

Configure your secrets in an .env file in the project root; the compose file mounts this into the container automatically.

Configuration Environment Variables

All runtime settings for your self-hosted CloddsBot instance are controlled through environment variables or a .env file. Key variables include:

ANTHROPIC_API_KEY=your-anthropic-key
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
WEBCHAT_TOKEN=your-webchat-token
CLODDS_STATE_DIR=/home/user/.clodds
CLODDS_PORT=18789

The clodds onboard wizard automatically creates ~/.clodds/.env with these values. Alternatively, manually copy .env.example from the repository root and populate the required fields before starting the gateway.

Starting the Gateway

Once configured, start the CloddsBot gateway to begin accepting connections:

clodds start

By default, the gateway listens on http://localhost:18789/webchat. Verify your self-hosted deployment using the built-in diagnostics:

clodds doctor        # System-wide health check

clodds creds test    # Validate API credential connectivity

The gateway exposes a health endpoint at GET /health that returns JSON status, useful for uptime monitoring and load balancers.

Testing Your Setup

Once the gateway runs on port 18789, open http://localhost:18789/webchat in your browser to interact with the AI. For programmatic trading, use the CLI:

clodds trade buy 100 YES "Trump wins" --platform polymarket

This command routes through src/agents/main-agent.ts, validates risk limits via src/risk/engine.ts, and executes via src/execution/executor.ts and src/execution/smart-router.ts.

Troubleshooting Common Setup Issues

When you set up CloddsBot for self-hosting, you may encounter these specific issues:

• ANTHROPIC_API_KEY not set – Re-run clodds onboard to regenerate the configuration file, or manually verify the variable exists in ~/.clodds/.env.

• Port 18789 already in use – Identify the conflicting process with lsof -i :18789 and terminate it, or override the default port via clodds config set gateway.port 18790.

• Telegram bot not responding – Ensure you are direct-messaging the bot rather than using a group chat, then run clodds doctor to verify network connectivity.

• Docker container exits immediately – Confirm all required environment variables are passed via -e flags or an .env file; missing variables cause the entrypoint script to fail before the gateway in src/gateway/index.ts initializes.

Summary

Setting up CloddsBot for self-hosting requires Node.js 22+, optional Python 3.x, and valid API credentials. You can deploy via:

• Global npm install for quick setups using the clodds onboard wizard.
• Source build for development and custom modifications to agents in src/agents/main-agent.ts or execution logic in src/execution/executor.ts.
• Docker or Docker Compose for containerized persistence with SQLite storage at CLODDS_STATE_DIR.

After installation, configure environment variables, start the gateway with clodds start, and verify health via clodds doctor or the /health endpoint.

Frequently Asked Questions

What are the minimum system requirements to set up CloddsBot for self-hosting?

You need Node.js version 22 or higher to execute the TypeScript gateway and CLI. Python 3.x is required only if you plan to run trading scripts like the Bittensor side-car. SQLite is bundled, so no separate database installation is necessary.

How do I persist data when running CloddsBot in Docker?

Set the CLODDS_STATE_DIR environment variable to a path inside the container (typically /data) and mount a Docker volume to that location. The SQLite database will be written to /data/clodds.db, ensuring your trades and user sessions survive container restarts.

Can I integrate custom messaging channels with my self-hosted CloddsBot?

Yes. Create a new adapter under src/channels/<yourchannel>/ that extends the BaseAdapter class defined in src/channels/base-adapter.ts, implementing the connect and sendMessage methods. Register your adapter in src/channels/index.ts to route messages through your custom channel.

Why does the gateway fail to start with an API key error even after I set the environment variable?

CloddsBot reads configuration from ~/.clodds/.env by default. If you set variables in your shell but the file contains different values, the file takes precedence. Run clodds onboard to synchronize the configuration, or manually edit ~/.clodds/.env to match your shell exports.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}