Skip to main content
The deploy command deploys your generated OpenClaw stack to Platform-as-a-Service (PaaS) providers like Dokploy or Coolify.

​
Usage

create-better-openclaw deploy [options]

​
Options

​
--dir
string
default:"."
Project directory containing the stack to deploy (default: current directory).
​
--provider
string
PaaS provider: dokploy or coolify. If not specified, you’ll be prompted interactively.
​
--url
string
PaaS instance URL (e.g., https://dokploy.example.com). Required for non-interactive mode.
​
--api-key
string
API key for the PaaS instance. Required for non-interactive mode.
​
--json
boolean
default:"false"
Output results as JSON for programmatic use.

​
Modes

​
Interactive mode

If you don’t provide all required options, the CLI will prompt you interactively: 
create-better-openclaw deploy
You’ll be asked to:
  1. Select a PaaS provider (Dokploy or Coolify)
  2. Enter the instance URL
  3. Enter your API key
  4. Confirm deployment

​
Non-interactive mode

Provide all required options for automated deployments: 
create-better-openclaw deploy --provider dokploy --url https://dokploy.example.com --api-key YOUR_API_KEY

​
Examples

​
Interactive deployment

cd my-stack
create-better-openclaw deploy
Output: 
Deploy OpenClaw Stack

? Select PaaS provider:
  > Dokploy
    Coolify

? Enter Dokploy instance URL: https://dokploy.example.com
? Enter API key: ****************************************

Connecting to Dokploy instance...
  ✓ Connection successful
  ✓ Authenticated

Deploying stack...
  ✓ Uploading docker-compose.yml
  ✓ Uploading .env
  ✓ Creating project
  ✓ Starting services

Deployment complete!

  Project URL: https://dokploy.example.com/projects/my-stack
  OpenClaw URL: https://openclaw.example.com

Services deployed:
  ✓ postgres
  ✓ redis
  ✓ qdrant
  ✓ openclaw

​
Deploy to Dokploy

create-better-openclaw deploy \
  --provider dokploy \
  --url https://dokploy.example.com \
  --api-key $DOKPLOY_API_KEY

​
Deploy to Coolify

create-better-openclaw deploy \
  --provider coolify \
  --url https://coolify.example.com \
  --api-key $COOLIFY_API_KEY

​
Deploy from specific directory

create-better-openclaw deploy \
  --dir ./production-stack \
  --provider dokploy \
  --url https://dokploy.example.com \
  --api-key $DOKPLOY_API_KEY

​
JSON output

create-better-openclaw deploy --provider dokploy --url https://dokploy.example.com --api-key $DOKPLOY_API_KEY --json
Output: 
{
  "success": true,
  "provider": "dokploy",
  "projectId": "proj_abc123",
  "projectUrl": "https://dokploy.example.com/projects/my-stack",
  "appUrl": "https://openclaw.example.com",
  "services": [
    {
      "name": "postgres",
      "status": "running",
      "url": null
    },
    {
      "name": "redis",
      "status": "running",
      "url": null
    },
    {
      "name": "qdrant",
      "status": "running",
      "url": null
    },
    {
      "name": "openclaw",
      "status": "running",
      "url": "https://openclaw.example.com"
    }
  ],
  "deployedAt": "2026-03-03T14:32:15Z"
}

​
Supported providers

​
Dokploy

Dokploy is a self-hosted PaaS alternative to Heroku and Vercel. Setup:
  1. Install Dokploy on your server
  2. Create an API key in Dokploy settings
  3. Use the Dokploy instance URL and API key with the deploy command
Features:
  • Automatic SSL with Let’s Encrypt
  • Built-in monitoring
  • Zero-downtime deployments
  • Docker Compose support

​
Coolify

Coolify is a self-hosted Heroku and Netlify alternative. Setup:
  1. Install Coolify on your server
  2. Generate an API token in Coolify settings
  3. Use the Coolify instance URL and API token with the deploy command
Features:
  • Git-based deployments
  • Automatic SSL
  • Resource monitoring
  • Docker Compose support

​
Requirements

​
Before deployment

Ensure your stack is generated and configured: 
# Generate stack
create-better-openclaw generate my-stack --preset researcher

# Review and customize
cd my-stack
vi .env

# Deploy
create-better-openclaw deploy

​
PaaS instance requirements

  • Running Dokploy or Coolify instance
  • API access enabled
  • Sufficient resources for your stack
  • Domain configured (for SSL)

​
Network requirements

  • HTTPS access to PaaS instance
  • Valid SSL certificate on PaaS instance
  • Firewall rules allowing deployment

​
Deployment workflow

The deploy command performs the following steps:
  1. Validation
    • Checks that stack files exist
    • Validates PaaS connection
    • Verifies API authentication
  2. Upload
    • Uploads docker-compose.yml
    • Uploads .env file (secrets handled securely)
    • Uploads additional configuration files
  3. Provisioning
    • Creates project in PaaS
    • Configures services
    • Sets environment variables
  4. Deployment
    • Pulls Docker images
    • Starts services
    • Configures networking
    • Sets up SSL (if configured)
  5. Verification
    • Checks service health
    • Verifies connectivity
    • Returns deployment URLs

​
Use cases

​
CI/CD deployment

# .github/workflows/deploy.yml
name: Deploy to Dokploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install better-openclaw
        run: npm install -g create-better-openclaw
      
      - name: Deploy stack
        run: |
          create-better-openclaw deploy \
            --provider dokploy \
            --url ${{ secrets.DOKPLOY_URL }} \
            --api-key ${{ secrets.DOKPLOY_API_KEY }} \
            --dir ./stack \
            --json
        env:
          DOKPLOY_URL: ${{ secrets.DOKPLOY_URL }}
          DOKPLOY_API_KEY: ${{ secrets.DOKPLOY_API_KEY }}

​
Multi-environment deployment

#!/bin/bash
# Deploy to different environments

case "$ENVIRONMENT" in
  staging)
    create-better-openclaw deploy \
      --provider dokploy \
      --url https://staging-dokploy.example.com \
      --api-key $STAGING_API_KEY
    ;;
  production)
    create-better-openclaw deploy \
      --provider dokploy \
      --url https://dokploy.example.com \
      --api-key $PROD_API_KEY
    ;;
esac

​
Blue-green deployment

# Deploy to new environment
create-better-openclaw deploy --provider dokploy --url $DOKPLOY_URL --api-key $API_KEY

# Test new deployment
curl -f https://new.openclaw.example.com/health || exit 1

# Switch traffic (manual or via PaaS UI)
echo "Deployment successful, switch traffic in Dokploy UI"

​
Troubleshooting

​
Connection refused

Check PaaS instance URL and network access: 
curl -I https://dokploy.example.com

​
Authentication failed

Verify API key: 
# Test API key with curl
curl -H "Authorization: Bearer $API_KEY" https://dokploy.example.com/api/health

​
Deployment timeout

Check service resource requirements: 
# Review stack resource usage
create-better-openclaw validate --dir ./my-stack

​
Service fails to start

Check PaaS logs:
  • Dokploy: Navigate to project → Logs
  • Coolify: Check deployment logs in UI

​
Security considerations

​
API key management

Never commit API keys to version control: 
# Use environment variables
export DOKPLOY_API_KEY="your-key-here"
create-better-openclaw deploy --provider dokploy --url $DOKPLOY_URL --api-key $DOKPLOY_API_KEY

# Or use secret management
API_KEY=$(aws secretsmanager get-secret-value --secret-id dokploy-api-key --query SecretString --output text)

​
Environment variables

The .env file is uploaded securely:
  • Encrypted during transfer
  • Stored securely in PaaS
  • Not exposed in logs

​
SSL/TLS

Ensure PaaS instance uses HTTPS: 
# Deploy will fail if using HTTP without --insecure flag (not recommended)
create-better-openclaw deploy --provider dokploy --url https://dokploy.example.com --api-key $API_KEY

Build docs developers (and LLMs) love

Get started for freeTalk to us