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

> Set up CloddsBot for self-hosting with our complete installation guide. Follow simple steps to install Node.js, configure API keys, and launch your bot quickly.

- Repository: [AL/CloddsBot](https://github.com/alsk1992/CloddsBot)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/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:

```bash
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`](https://github.com/alsk1992/CloddsBot/blob/main/src/agents/main-agent.ts), build from the GitHub repository:

```bash
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`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/index.ts).

### Docker Single Container

Deploy CloddsBot as a single container for simplified dependency management:

```bash
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`](https://github.com/alsk1992/CloddsBot/blob/main/docker-compose.yml):

```bash

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

```dotenv
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:

```bash
clodds start

```

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

```bash
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:

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

```

This command routes through [`src/agents/main-agent.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/agents/main-agent.ts), validates risk limits via [`src/risk/engine.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/risk/engine.ts), and executes via [`src/execution/executor.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/execution/executor.ts) and [`src/execution/smart-router.ts`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/src/agents/main-agent.ts) or execution logic in [`src/execution/executor.ts`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/src/channels/base-adapter.ts), implementing the `connect` and `sendMessage` methods. Register your adapter in [`src/channels/index.ts`](https://github.com/alsk1992/CloddsBot/blob/main/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.