Komus Tasks Server

Production-grade task execution server with web UI, webhooks, scheduling, and multi-task support.

Installation

First public PyPI release: 1.0.0.

pip install ko-tasks-server

Quick Start

Start the server

ko-tasks-server takes no flags — configure it with environment variables:

export PORT=3000
export BASE_PATH=/var/lib/ko-tasks-server
export API_KEYS=your-api-key
export ADMIN_API_KEYS=your-admin-key
ko-tasks-server

Access

Configuration

Environment Variables

S3 Storage (optional)

export FILE_STORAGE_TYPE=s3
export S3_BUCKET=my-task-artifacts
export S3_REGION=eu-west-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

Elasticsearch (optional)

export STORAGE_TYPE=elasticsearch
export ELASTICSEARCH_HOSTS=http://localhost:9200

Deployment

Docker

docker build -t ko-tasks-server .
docker run -p 3000:3000 \
  -e API_KEYS=your-key \
  -e ADMIN_API_KEYS=your-admin-key \
  -v ./data:/data \
  ko-tasks-server

Docker Compose

docker-compose up -d

Pre-configured variants:

• docker-compose.yml — Basic setup
• docker-compose.elasticsearch.yml — With Elasticsearch
• docker-compose.cloud.yml — Cloud-ready with S3
• docker-compose.standalone.yml — Standalone mode

API Overview

Task Management (Admin)

# Deploy a task
curl -X POST http://localhost:3000/admin/tasks \
  -H "X-Admin-API-Key: your-admin-key" \
  -F "file=@my-task-1.0.0.zip"

# List deployed tasks
curl http://localhost:3000/admin/tasks \
  -H "X-Admin-API-Key: your-admin-key"

Thread Execution

# Create and run a thread
curl -X POST http://localhost:3000/threads \
  -H "X-API-Key: your-key" \
  -H "X-App-Id: my-app" \
  -H "X-User-Id: user-1" \
  -H "Content-Type: application/json" \
  -d '{"mode": "sync", "inputs": [{"kind": "text", "text": "Hello"}]}'

# Get thread status
curl http://localhost:3000/threads/{thread_id} \
  -H "X-API-Key: your-key"

# Pause/Resume
curl -X POST http://localhost:3000/threads/{thread_id}:pause \
  -H "X-API-Key: your-key"
curl -X POST http://localhost:3000/threads/{thread_id}:resume \
  -H "X-API-Key: your-key"

Webhooks

# Create a webhook
curl -X POST http://localhost:3000/webhooks \
  -H "X-Admin-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/task-events",
    "events": ["thread.succeeded", "thread.failed"],
    "secret": "webhook-signing-secret"
  }'

Schedules

# Create a schedule
curl -X POST http://localhost:3000/schedules \
  -H "X-Admin-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "my-task",
    "cron": "0 8 * * MON",
    "timezone": "Europe/Paris",
    "inputs": [{"kind": "text", "text": "Weekly run"}]
  }'

Features

• Multi-task deployment with isolated code + venv per task
• Worker subprocess isolation with JSON Lines IPC
• Progress, pause, resume, cancel — cooperative task control
• Python & Node.js task runtimes
• Web Dashboard — full CRUD for all resources
• Webhook system — HMAC-signed, scoped, with delivery tracking
• Cron scheduling — with concurrency policies
• Artifact management — local or S3 storage
• Credential vault — AES-encrypted secret storage
• Prometheus metrics — request counts, durations, thread states
• Idempotency — duplicate request detection

Development

# Clone and setup
git clone https://github.com/Komus-ai/ko-tasks-platform.git
cd ko-tasks-platform
uv sync

# Run server tests
uv run --package ko-tasks-server pytest packages/server/tests/ -v

# Start dev server
uv run --package ko-tasks-server python -m komus_tasks_server.server

License

MIT