Installation

description: “Self-host Agentbot”

Installation

Run Agentbot locally or self-host on your own infrastructure.

Prerequisites

• Node.js 22.x (>=22.14.0 required for OpenClaw runtime)
• PostgreSQL database
• Docker (for agent containers)

Quick Start (Dev Container)

The fastest way to start developing:

1. Install the Dev Containers extension for VS Code
2. Open the project in VS Code
3. Click “Reopen in Container” when prompted

Or use Factory Cloud Templates for instant cloud-hosted development with zero setup.

Local Development

# Clone the repository
git clone https://github.com/Eskyee/agentbot-opensource.git
cd agentbot-opensource

# Install dependencies
cd web && npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# Run the development server
npm run dev

SDK Options

If you want to integrate with Agentbot programmatically, use one of these public options:

• sdk/agentbot in agentbot-opensource for the typed reference API client
• Eskyee/agentbot-sdk for the standalone SDK repo

For the reference client:

import { createAgentbotClient } from './sdk/agentbot/index'

const client = createAgentbotClient({
  baseUrl: 'http://localhost:3001',
  apiKey: process.env.AGENTBOT_API_KEY,
})

const agents = await client.listAgents()

Environment Variables

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/agentbot

# Auth
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000

# GitHub OAuth
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# Google OAuth
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# OpenRouter (default AI provider)
OPENROUTER_API_KEY=sk-or-...

# Telegram Bot
TELEGRAM_BOT_TOKEN=your-bot-token

# Railway provisioning (required for managed agent deployment)
RAILWAY_API_KEY=your-railway-api-key
RAILWAY_TOKEN_TYPE=account
RAILWAY_PROJECT_ID=your-railway-project-id
RAILWAY_ENVIRONMENT_ID=your-railway-environment-id

# OpenClaw Gateway (optional — defaults to internal Railway DNS)
OPENCLAW_GATEWAY_URL=http://your-gateway-host:10000

RAILWAY_TOKEN_TYPE controls how the platform authenticates with the Railway GraphQL API. Set it to project to authenticate with a project-scoped token (sent via the Project-Access-Token header) or to account (default) to authenticate with a personal token (sent via the Authorization: Bearer header). Valid values are project, workspace, account, and oauth.

Docker Production

# docker-compose.yml
version: '3.8'
services:
  web:
    image: agentbot/web:latest
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data
    env_file:
      - .env

  agentbot-backend:
    image: ghcr.io/raveculture/agentbot-backend:latest
    init: true
    ports:
      - "18789:18789"
    environment:
      - HOME=/home/node
      - TERM=xterm-256color
      - NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
      - OPENCLAW_NO_RESPAWN=1
    env_file:
      - .env

volumes:
  postgres_data:

The init: true flag enables proper signal forwarding and prevents zombie processes (PID 1 handling). The HOME and TERM environment variables are required by the official OpenClaw image which runs as the node user. NODE_COMPILE_CACHE enables the Node.js compile cache for faster startup, and OPENCLAW_NO_RESPAWN=1 prevents the OpenClaw process from automatically respawning inside the container (Docker’s restart policy handles restarts instead).

docker-compose up -d

Deployment

Vercel (Recommended)

1. Push code to GitHub
2. Import project in Vercel
3. Add environment variables
4. Deploy

Railway

railway init
railway up

DigitalOcean

Use the One-Click App for Node.js and connect a managed PostgreSQL database.

Verify Installation

After deployment, visit:

• Main app: https://your-domain.com
• Health check: https://your-domain.com/health

Troubleshooting

Database connection failed

Check your DATABASE_URL format:

postgresql://username:password@host:5432/database

OAuth not working

Ensure your OAuth redirect URLs match:

• Development: http://localhost:3000/api/auth/callback/github
• Production: https://your-domain.com/api/auth/callback/github