Coolify deployment

Coolify is a self-hosted PaaS alternative to Vercel. better-openclaw can deploy generated stacks directly to your Coolify instance via the CLI or web UI.

Prerequisites

A running Coolify instance (v4.0+)
Coolify API token
At least one server registered in Coolify
Generated stack with docker-compose.yml and .env

Setup Coolify

If you don’t have Coolify installed, follow the official installation guide:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

Access the dashboard at http://your-server-ip:8000.

Generate an API token

Open Coolify dashboard

Navigate to your Coolify instance dashboard.

Go to Keys & Tokens

Click on Keys & Tokens in the sidebar.

Create API token

Click API Tokens > Create.Set:

Name: better-openclaw
Permission: * (full access)

Copy the token immediately — it won’t be shown again.

Deploy via CLI

Interactive mode

Run the deploy command in your generated stack directory:

cd my-openclaw-stack
npx create-better-openclaw deploy

The wizard will prompt for:

Platform: Select Coolify
Instance URL: Your Coolify instance (e.g., https://coolify.example.com)
API key: Paste the token from above

The CLI will:

Test the connection
Discover the first available server
Create a Coolify project
Create a compose service
Push environment variables
Trigger the deployment

Non-interactive mode

For CI/CD pipelines, provide all flags:

npx create-better-openclaw deploy \
  --provider coolify \
  --instance-url https://coolify.example.com \
  --api-key YOUR_API_TOKEN \
  --dir ./my-openclaw-stack

Add --json for machine-readable output:

npx create-better-openclaw deploy \
  --provider coolify \
  --instance-url https://coolify.example.com \
  --api-key YOUR_API_TOKEN \
  --dir ./my-openclaw-stack \
  --json

Deploy via Web UI

Generate stack in Web UI

Open the better-openclaw web UI at http://localhost:3654.Select services, proxy, and configuration options.

Click 'Deploy'

After generating the stack, click the Deploy to PaaS button.

Configure deployment

Select Coolify as the provider.Enter:

Instance URL: https://coolify.example.com
API Key: Your Coolify token

Deploy

Click Deploy. The UI will show real-time progress for each step.When complete, a link to the Coolify dashboard will be displayed.

Deployment workflow

The deployer follows these steps:

Discover server

Queries Coolify for available servers and selects the first one.API endpoint: GET /api/v1/serversThe deployer uses the first server’s UUID for deployment.

Create project

Creates a new Coolify project with the stack name.API endpoint: POST /api/v1/projects

Create compose service

Creates a Docker Compose service inside the project’s production environment.API endpoint: POST /api/v1/servicesUploads the generated docker-compose.yml via the docker_compose_raw field.

Set environment variables

Pushes all variables from .env to the compose service.API endpoint: PATCH /api/v1/services/{uuid}/envsEach variable is sent with:

is_preview: false — Production environment
is_build_time: false — Runtime variable
is_literal: true — Use raw value

Trigger deployment

Starts the deployment process.API endpoint: GET /api/v1/deploy?uuid={service_uuid}&force=trueCoolify will:

Pull Docker images
Create volumes and networks
Start services with health checks

Monitoring deployment

CLI output

The CLI displays step-by-step progress:

Deploying to Coolify...
  Instance: https://coolify.example.com
  Project:  my-openclaw-stack

Testing connection...
Connection OK

  done  Discover server (Server: prod-1 (192.168.1.10))
  done  Create project (Project: abc123-def456-ghi789)
  done  Create compose service (Service: xyz789-uvw456-rst123)
  done  Set environment variables (12 variables set)
  done  Trigger deployment (Deployment triggered)

Deployed successfully!
  Dashboard: https://coolify.example.com/project/abc123-def456-ghi789

Coolify dashboard

Open the dashboard URL to:

View deployment logs
Monitor service health
Manage environment variables
Configure domains and SSL

Managing deployed stacks

Update environment variables

Edit .env locally

Update your local .env file with new values.

Redeploy

Run the deploy command again:

npx create-better-openclaw deploy

The deployer will update variables and redeploy.

Alternatively, edit variables directly in the Coolify dashboard:

Navigate to Project > Service
Click Environment Variables
Edit values and click Save
Click Redeploy

View logs

Stream logs for a service:

Navigate to Project > Service
Click Logs tab
Select a container from the dropdown
Logs will stream in real-time

Redeploy stack

Trigger a redeployment:

Navigate to Project > Service
Click Deploy button
Confirm the deployment

Configure domains

Add a custom domain:

Navigate to Project > Service
Click Domains tab
Click Add Domain
Enter your domain (e.g., app.example.com)
Enable Generate SSL Certificate for automatic Let’s Encrypt SSL
Click Save

Update your DNS to point to the Coolify server IP.

CI/CD integration

GitHub Actions

name: Deploy to Coolify

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate stack
        run: |
          npx create-better-openclaw@latest \
            --preset researcher \
            --yes \
            --output ./stack

      - name: Deploy to Coolify
        run: |
          npx create-better-openclaw deploy \
            --provider coolify \
            --instance-url ${{ secrets.COOLIFY_URL }} \
            --api-key ${{ secrets.COOLIFY_API_KEY }} \
            --dir ./stack \
            --json

GitLab CI

deploy:
  stage: deploy
  script:
    - npx create-better-openclaw@latest --preset researcher --yes --output ./stack
    - npx create-better-openclaw deploy --provider coolify --instance-url $COOLIFY_URL --api-key $COOLIFY_API_KEY --dir ./stack --json
  only:
    - main

Troubleshooting

Connection failed

Error: Coolify API 401: Unauthorized Solution: Verify your API token:

Regenerate token in Coolify dashboard
Ensure token has * permission
Check for typos in the token

No servers found

Error: No servers found in Coolify instance Solution: Register a server in Coolify:

Navigate to Servers > Add Server
Follow the setup wizard to connect your server
Wait for the server to become “Validated”

Project creation failed

Error: Coolify API 409: Conflict Solution: The project name is already in use. Either:

Delete the existing project in Coolify
Regenerate the stack with a different name

Deployment timeout

Error: Services taking too long to start Solution:

Check service logs in Coolify dashboard
Verify image availability (check Docker Hub/registry)
Increase health check intervals in docker-compose.yml

Environment variables not applied

Error: Services fail due to missing env vars Solution:

Ensure .env file exists in the stack directory
Check that all required variables are set
Manually verify variables in Coolify dashboard under Environment Variables
Redeploy to push updated variables

API reference

The Coolify deployer uses these API endpoints:

Endpoint	Method	Purpose
`/api/v1/version`	GET	Test connection
`/api/v1/servers`	GET	Discover servers
`/api/v1/projects`	POST	Create project
`/api/v1/projects/{uuid}`	GET	Get project details
`/api/v1/services`	POST	Create compose service
`/api/v1/services/{uuid}/envs`	PATCH	Update environment variables
`/api/v1/deploy`	GET	Trigger deployment

Authentication: Authorization: Bearer <token> See the Coolify API docs for full reference.

Environment variable schema

When pushing variables via the bulk env API, each variable is sent with this structure:

{
  "key": "DATABASE_URL",
  "value": "postgresql://user:pass@localhost:5432/db",
  "is_preview": false,
  "is_build_time": false,
  "is_literal": true
}

is_preview: false — Production environment
is_build_time: false — Runtime variable (not baked into image)
is_literal: true — Use raw value (no variable interpolation)

Next steps

Dokploy deployment for an alternative PaaS
Docker deployment for local development
VPS deployment for manual cloud setup

Get Started

Core Concepts

CLI Guide

Configuration

Deployment

Guides

Prerequisites

Setup Coolify

Generate an API token

Deploy via CLI

Interactive mode

Non-interactive mode

Deploy via Web UI

Deployment workflow

Monitoring deployment

CLI output

Coolify dashboard

Managing deployed stacks

Update environment variables

View logs

Redeploy stack

Configure domains

CI/CD integration

GitHub Actions

GitLab CI

Troubleshooting

Connection failed

No servers found

Project creation failed

Deployment timeout

Environment variables not applied

API reference

Environment variable schema

Next steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Guide

Configuration

Deployment

Guides

​Prerequisites

​Setup Coolify

​Generate an API token

​Deploy via CLI

​Interactive mode

​Non-interactive mode

​Deploy via Web UI

​Deployment workflow

​Monitoring deployment

​CLI output

​Coolify dashboard

​Managing deployed stacks

​Update environment variables

​View logs

​Redeploy stack

​Configure domains

​CI/CD integration

​GitHub Actions

​GitLab CI

​Troubleshooting

​Connection failed

​No servers found

​Project creation failed

​Deployment timeout

​Environment variables not applied

​API reference

​Environment variable schema

​Next steps

Build docs developers (and LLMs) love

Prerequisites

Setup Coolify

Generate an API token

Deploy via CLI

Interactive mode

Non-interactive mode

Deploy via Web UI

Deployment workflow

Monitoring deployment

CLI output

Coolify dashboard

Managing deployed stacks

Update environment variables

View logs

Redeploy stack

Configure domains

CI/CD integration

GitHub Actions

GitLab CI

Troubleshooting

Connection failed

No servers found

Project creation failed

Deployment timeout

Environment variables not applied

API reference

Environment variable schema

Next steps