How to set up Moltbot on a private server

Setting up Moltbot (formerly known as Clawdbot) on a private server involves preparing your VPS (Virtual Private Server) environment, cloning the Moltbot repository, running the Docker setup script, configuring your AI provider credentials, and connecting to a messaging platform.

It’s a straightforward process that takes about 30 minutes from start to finish, and by the end, you’ll have your own AI assistant responding to messages 24/7.

You can technically run Moltbot on your own laptop, but that has limits. If you close your computer or lose internet connection, your bot goes offline.

That’s why running it on a private server is so helpful. It provides consistent availability and background execution, even when you’re offline, so your bot runs 24/7 without you needing to babysit it.

1. Prepare a private server for Moltbot

To prepare a private server for Moltbot, you need a Linux VPS with full administrative access. This is the foundation of your project because an always-on server ensures your bot never sleeps.

You don’t need a supercomputer for this, but you do need specific Moltbot server requirements to ensure stability.

Here is your checklist for the server:

• Linux operating system (Ubuntu 22.04 or 24.04 works great).
• Administrative access (root or sudo privileges).
• Docker and Docker Compose.
• At least 2GB RAM (4GB recommended for better performance).
• 10GB+ disk space for Docker images, application data, and logs.

We’ll be using Hostinger Moltbot hosting for this setup, because our Docker Manager makes things easier, but the same principles apply to any other VPS provider.

If you’re brand new to VPS setup, learn how to set up VPS first. Follow the initial setup there to make sure you can SSH into your server.

2. Make sure Docker is available on the VPS

Docker is how we’ll run Moltbot. Think of Docker as a container that packages everything Moltbot needs into one tidy unit. Instead of manually installing dependencies and configuring different details, Docker handles it all. It’s cleaner, more reliable, and way easier to manage.

Within Hostinger’s hPanel dashboard, look for Docker Manager. It should show Docker as installed or give you an option to enable it. That’s the easiest path.

If you’re on a different VPS or want to verify from the command line, SSH into your server and run:

docker --version

docker compose version

You should see version numbers for both Docker and Docker Compose. If you get “command not found,” Docker isn’t installed yet.

A proper Moltbot Docker setup relies on the Docker container system being healthy, so to install it manually, learn how to install Docker on Ubuntu, and then verify it again.

Once Docker is confirmed and running, you’re ready for the actual Moltbot deployment.

3. Clone the Moltbot repository

Now we’re getting to the good stuff. We’re going to clone the Moltbot repository and use the official Docker setup script to build and deploy everything.

First, you need to get the Moltbot code on your server:

# Install git if you don't have it

sudo apt install git -y

# Clone the repository

git clone https://github.com/moltbot/moltbot.git

# Navigate into the directory

cd moltbot

Then run the Docker setup script. Moltbot includes a setup script that handles everything automatically:

./docker-setup.sh

This setup script is your one-stop shop for getting Moltbot running. Here’s what it does:

1. Builds the Moltbot Docker image locally (from the included Dockerfile).
2. Runs the onboarding wizard inside a Docker container.
3. Generates a gateway token for accessing the Control UI.
4. Creates necessary configuration directories.
5. Starts the Moltbot gateway via Docker Compose.

The entire process is automated. Unlike many Docker applications, where you pull a pre-built image, Moltbot builds the image locally on your server. This means:

• You’re always running the exact version from the repository.
• The first build takes a few minutes.
• Subsequent rebuilds are faster thanks to Docker’s layer caching.
• You have full control over what’s included.

4. Configure Moltbot credentials and settings

The Docker setup script launches an interactive onboarding wizard that configures Moltbot for you. This is where you’ll set up your AI provider credentials and other essential settings.

When you run ./docker-setup.sh, after building the image, you’ll see the onboarding wizard. It asks several important questions:

Gateway mode:

• Local (run on this machine)
• Remote (connect to existing gateway)

Choose Local. This means the gateway runs on your VPS.

Authentication method:

This is the most critical part. You need to tell Moltbot how to access AI models:

• Anthropic API Key (recommended)
• OpenAI API Key
• OAuth (Claude Pro/Max subscription)
• OpenAI Code (Codex subscription)

If you go with the recommended option of Anthropic API Key, then you need to sign up or log in to Anthropic, navigate to API Keys, create a new key, copy it, and paste it into the setup wizard.

Keep this key secure. Anyone with this key can use Claude on your account and you’ll be charged for their usage.

The process is the same with the other options – you get a key from the AI platform, and add it into the setup. The wizard stores these credentials as Linux environment variables in your configuration files.

You then choose the model for the selected AI platform and pick security settings.

The most common Moltbot config mistake is a missing API key. Without a valid Anthropic or OpenAI API key, Moltbot won’t work. Both Anthropic and OpenAI require a payment method on file for API access, so make sure your API key is active and has billing set up.

5. Start Moltbot and verify it is running

Once the setup script completes, Moltbot should already be running.

To verify everything is working correctly, check the container status:

# Make sure you're in the moltbot directory

cd ~/moltbot

# Check running containers

docker compose ps

You should see moltbot-gateway with status “Up” or “Running”. Other signs that everything is working correctly include seeing:

• A “Moltbot initialized” message
• Model provider connected (Anthropic/OpenAI)
• No authentication errors

On the other hand, if you see “Invalid API key,” “Authentication failed,” “Connection refused,” or if the container just keeps restarting, then you’ve got an error.

Stop here and fix them before continuing by checking the logs:

docker compose logs moltbot-gateway

This is important for troubleshooting. The Moltbot logs tell you what the bot is actually doing, so you can address the issues.

6. Access the Moltbot interface

Moltbot dashboard is accessible via your VPS IP address on port 18789:

http://your-vps-ip:18789

For example: http://45.123.45.67:18789

When you first visit the Control UI, you’ll need the gateway token that was generated during setup. Find it in:

cat ~/.clawdbot/.env | grep CLAWDBOT_GATEWAY_TOKEN

Or check the output from when you ran ./docker-setup.sh – it displays the token at the end.

Note: While the project has been renamed to Moltbot, configuration files and directories still use “clawdbot” naming (like ~/.clawdbot/ and CLAWDBOT_GATEWAY_TOKEN). This is normal during the transition and doesn’t affect functionality.

Once you’re in the dashboard, go to Settings → Token (or you may be prompted immediately). Paste your gateway token, then click Save or Authenticate.

This Moltbot interface is your control center. You don’t need to configure everything right now – just confirm you can access it and that Moltbot shows as healthy.

If you can’t reach the interface, follow these troubleshooting steps:

• Check that the container is actually running: docker compose ps
• Verify your firewall isn’t blocking the port
• Make sure you’re using HTTP, not HTTPS
• Try accessing from the server itself in the command line: curl http://localhost:18789

7. Connect a messaging channel to Moltbot

The web dashboard we just configured is for management, but you’ll interact with Moltbot via a messaging app where AI conversations take place.

We’ll go through how to set things up with Telegram since it’s straightforward, but the process is similar for other platforms.

Here is how to handle a Moltbot Telegram setup:

Step 1: Create a Telegram bot

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Choose a name (for example, My Moltbot Assistant)
   • Choose a username (must end in “bot”, like “myawesomemoltbot”)
4. BotFather will give you a bot token. Copy this.

Step 2: Add Telegram to Moltbot

Back on your server, run:

# Make sure you're in the moltbot directory

cd ~/moltbot

# Add Telegram with your bot token

docker compose run --rm moltbot-cli providers add --provider telegram --token YOUR_BOT_TOKEN

Replace YOUR_BOT_TOKEN with the actual token from BotFather.

Step 3: Enable required bot permissions

In the BotFather chat:

1. Send /mybots
2. Select your bot
3. Go to Bot Settings → Group Privacy
4. Disable group privacy (this allows the bot to read messages in groups)

Step 4: Start chatting

1. Open Telegram and search for your bot (by the username you chose)
2. Start a conversation
3. Send a message to test it

If you set up DM pairing during setup, you’ll get a pairing code. On your server, approve it:

docker compose run --rm moltbot-cli pairing approve telegram <the-code-you-received>

After approval, send another message. Moltbot should respond!

If messages aren’t working in your Moltbot Telegram setup:

• Check the Moltbot logs for errors.
• Verify the API keys are still valid.
• Make sure the container didn’t restart or crash.
• Confirm your messaging platform credentials are correct.

How to troubleshoot common Moltbot setup issues

To troubleshoot common Moltbot setup issues, check container status first, verify your gateway token, and examine the logs for specific error messages. Most problems fall into a few predictable categories, and once you know what to look for, they’re quick to fix.

Here are the most common problems you might encounter with Moltbot not working.

Container keeps stopping

If your container starts, then immediately stops:

1. Check container status: docker compose ps
2. View logs for errors: docker compose logs moltbot-gateway
3. Look for the specific error: docker compose logs moltbot-gateway | grep -i “error”

Common causes include a missing or invalid API key, port 18789 already in use, Docker Compose configuration issues, or insufficient permissions.

Authentication failures

The most common problem by far. If you see “authentication failed”, “invalid API key”, or model requests failing, then check your API key:

cat ~/.clawdbot/.env

Look for ANTHROPIC_API_KEY or OPENAI_API_KEY. Make sure:

• The key is present and not empty
• There are no extra spaces or quotes
• The key hasn’t been revoked or expired

You also need to verify the key is valid in the AI platform dashboard and check the billing status, as both Anthropic and OpenAI require active billing.

Then re-add your credentials:

# Edit the .env file

nano ~/.clawdbot/.env

# Add or update your API key

ANTHROPIC_API_KEY=your_actual_key_here

# Restart the gateway

docker compose restart moltbot-gateway

Port conflicts

If you get “port already in use” or “address already in use” errors:

• Check what’s using the port: sudo lsof -i :18789
• Change Moltbot’s port by editing docker-compose.yml
• Use a different port mapping: -p 18790:18789

Container restart loops

If the container keeps restarting, this usually means there are missing environment variables, corrupted configuration files, invalid model configuration, or permission issues.

To fix this:

• Stop everything: docker compose down
• Remove old containers and volumes: docker compose down -v
• Rebuild and restart: ./docker-setup.sh

Can’t access the interface

If the container is running but you can’t reach the dashboard:

• Check firewall rules and allow port 18789: sudo ufw allow 18789/tcp
• Verify the container is listening: curl http://localhost:18789
• Check VPS provider settings since some providers require you to configure security groups to allow inbound traffic on port 18789

Restarting safely

You’ll need to restart Moltbot when you change environment variables, if the bot becomes unresponsive, or after specific configuration updates.

A restart is also useful for troubleshooting weird behavior, since a fresh start can clear up issues that don’t show obvious errors in the logs.

If you need to restart Moltbot quickly without stopping the container first:

docker restart moltbot-gateway

Or for a clean restart where you manually stop and then start the container (useful when you want more control over the process or need to verify the container stops completely):

docker stop moltbot-gateway

docker start moltbot-gateway

What are the best practices for running Moltbot?

Best practices for running Moltbot include keeping your gateway token secure, monitoring resource usage regularly, and staying current with updates.

Running an AI bot on a server comes with responsibilities, but they’re manageable if you establish good habits early in specific areas.

Security practices

• Never share your gateway token. Treat it like a password because anyone who has it can control your bot.
• Use a firewall. Only expose the ports you actually need (like port 18789 for the interface).
• Keep SSH secure. Use key-based authentication instead of passwords for server access.
• Restrict interface access. Consider using a VPN or IP whitelist if you don’t need public access to the dashboard.

Resource management

Moltbot is relatively lightweight, but you should still keep an eye on:

• Memory usage. Check occasionally with docker stats moltbot-gateway
• Disk space. Logs can accumulate. Consider log rotation if running long-term.
• CPU usage. Spikes are normal during active conversations, but sustained high usage might indicate a problem.

If you notice resource issues, you might need to upgrade your VPS or investigate what’s causing excessive usage.

Update strategy

New Moltbot versions are released periodically with improvements and fixes.

• Check for updates monthly (or subscribe to Moltbot announcements).
• Test updates in a non-production environment first if possible.
• Keep a backup of your current working configuration before updating.
• Read release notes to understand what changed.

Monitoring uptime

Set up basic monitoring so you know if Moltbot goes down:

• Docker’s restart policy helps with automatic recovery.
• Consider a simple uptime monitor (many free services exist).
• Check logs periodically for unusual errors or warnings.
• Test your messaging channels occasionally to confirm functionality.

Backup configuration

Your environment variables (especially that gateway token) are essential to the setup. Document them securely:

• Store your token in a password manager.
• Keep notes on your configuration settings.
• Document any custom environment variables you’ve added.

How to manage Moltbot after setup

To manage Moltbot after setup, monitor logs regularly, update the container when new versions are released, and keep an eye on performance metrics.

Day-to-day management is minimal once everything is running smoothly, but a little ongoing attention keeps things healthy. Here’s what you need to do.

Check logs regularly

Make it a habit to peek at the logs weekly using:

docker compose logs --tail 100 moltbot-gateway

Look for repeated errors or warnings, performance issues, connection problems, or unusual patterns.

Most of the time, you’ll see regular operation, but catching issues early prevents bigger problems.

Update Moltbot

When a new version is released, use the setup script to pull the latest code:

git pull

Then rerun setup (this preserves your config):

./docker-setup.sh

Monitor uptime

Check container status periodically. It should show status as “Up,” but if it’s restarting frequently, investigate the logs.

Monitor performance

Every few weeks, check resource usage:

docker stats moltbot-gateway

This shows CPU, memory, and network usage in real-time. If usage seems high, you might need to:

• Investigate what’s causing it (check logs)
• Upgrade your VPS if you’ve outgrown the current specs
• Optimize your configuration

You don’t need to worry about scaling, clustering, or complex optimizations for most use cases. Moltbot runs well on a single VPS for personal or small team use.

Focus on keeping it running reliably, updating when needed, monitoring for errors, and maintaining security basics.

For quick reference to Docker commands you’ll use while managing Moltbot, see this Docker cheat sheet.