Imported from terminalskills/skills (skills/koyeb/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill koyeb. Copyright stays with the author (Apache-2.0).

Koyeb — Global Serverless Platform

Overview

Koyeb, the serverless cloud platform for deploying full-stack applications, APIs, and workers globally with automatic scaling, built-in CI/CD, and edge networking. Helps developers deploy applications from Git or Docker with zero-downtime deployments and pay-per-use pricing.

Instructions

CLI Deployment

# Install Koyeb CLI
curl -fsSL https://raw.githubusercontent.com/koyeb/koyeb-cli/master/install.sh | sh

# Login
koyeb login

# Deploy from a Git repository
koyeb app create my-api
koyeb service create my-api/web \
  --git github.com/myorg/my-api \
  --git-branch main \
  --git-build-command "npm ci && npm run build" \
  --git-run-command "node dist/index.js" \
  --port 3000:http \
  --region fra \
  --instance-type nano \
  --min-scale 1 \
  --max-scale 5 \
  --env NODE_ENV=production \
  --env DATABASE_URL=@database-url   # Reference a secret

# Deploy from Docker image
koyeb service create my-api/web \
  --docker ghcr.io/myorg/my-api:latest \
  --port 3000:http \
  --region fra

# Manage secrets
koyeb secret create database-url --value "postgres://..."
koyeb secret list

# Custom domains
koyeb domain create api.myapp.com --app my-api

Service Configuration (koyeb.yaml)

# koyeb.yaml — Declarative service configuration
name: my-api
type: web

# Build configuration
git:
  repository: github.com/myorg/my-api
  branch: main
  build_command: npm ci && npm run build
  run_command: node dist/index.js

# Or Docker-based
# docker:
#   image: ghcr.io/myorg/my-api:latest

# Scaling
scaling:
  min: 1
  max: 10
  targets:
    - metric: cpu
      value: 70              # Scale up at 70% CPU
    - metric: requests
      value: 100             # Scale up at 100 req/s per instance

# Instance configuration
instance_type: small          # nano | small | medium | large | xlarge
regions:
  - fra                       # Frankfurt
  - was                       # Washington DC
  - sin                       # Singapore

# Networking
ports:
  - port: 3000
    protocol: http

# Health checks
health_checks:
  - type: http
    port: 3000
    path: /health
    interval: 30
    timeout: 10
    healthy_threshold: 2
    unhealthy_threshold: 3

# Environment
env:
  - key: NODE_ENV
    value: production
  - key: DATABASE_URL
    secret: database-url     # Reference a Koyeb secret
  - key: REDIS_URL
    secret: redis-url

# Volumes (persistent storage)
volumes:
  - name: data
    path: /app/data
    size: 10                  # GB

Workers and Cron Jobs

# Deploy a background worker (no public port)
koyeb service create my-app/worker \
  --git github.com/myorg/my-api \
  --git-branch main \
  --git-run-command "node dist/worker.js" \
  --type worker \
  --env QUEUE_URL=@queue-url

# There's no native cron in Koyeb — use a lightweight scheduler
# or a cron-to-HTTP service that hits your web endpoint

Multi-Region Deployment

# Deploy to multiple regions for global low-latency
koyeb service update my-api/web \
  --region fra,was,sin \
  --min-scale 1 \
  --max-scale 3

# Koyeb's edge network automatically routes users to the nearest region
# DNS-based routing: requests from Europe → Frankfurt, US → Washington, Asia → Singapore

Database Integration

# Koyeb offers managed Postgres (Neon-powered)
koyeb database create main-db \
  --engine postgres \
  --region fra

# Connection string is available as a secret
# Reference it in service env vars:
koyeb service update my-api/web \
  --env DATABASE_URL=@main-db-connection-string

Examples

Example 1: Setting up Koyeb for a microservices project

User request:

I have a Node.js API and a React frontend running in Docker. Set up Koyeb for monitoring/deployment.

The agent creates the necessary configuration files based on patterns like # Install Koyeb CLI, sets up the integration with the existing Docker setup, configures appropriate defaults for a Node.js + React stack, and provides verification commands to confirm everything is working.

Example 2: Troubleshooting service configuration issues

User request:

Koyeb is showing errors in our service configuration. Here are the logs: [error output]

The agent analyzes the error output, identifies the root cause by cross-referencing with common Koyeb issues, applies the fix (updating configuration, adjusting resource limits, or correcting syntax), and verifies the resolution with appropriate health checks.

Guidelines

1. Use Git-based deployment — Push to deploy; Koyeb handles builds, caching, and zero-downtime rollouts
2. Multi-region for latency — Deploy to regions closest to your users; Koyeb's edge routes traffic automatically
3. Secrets for credentials — Never put database URLs or API keys in env vars directly; use koyeb secret create
4. Autoscaling with request metrics — Scale on requests-per-second for web services; CPU-based for compute-heavy workers
5. Health checks are critical — Define HTTP health checks; without them, Koyeb can't do zero-downtime deployments
6. Use nano for staging — Nano instances are cheap; use them for preview/staging environments
7. Pin Docker tags — Don't use :latest in production; pin to specific versions for reproducible deployments
8. Monitor via dashboard — Koyeb provides built-in logs, metrics, and deployment history in the web console