taskrun

AI Task Orchestration Platform - Delegate complex, multi-step tasks to autonomous AI agents with full observability and control.

Quick Start

1. Setup Claude Code Token

# Get your OAuth token from Claude
claude setup-token

# Export the token
export CLAUDE_CODE_OAUTH_TOKEN=<your-token>

2. Start Infrastructure

# Start PostgreSQL and Redis (non-default ports to avoid conflicts)
docker compose up -d

# Verify services are running
docker compose ps

3. Setup Database

# Install dependencies
npm install

# Run migrations
npx prisma migrate dev

# (Optional) Open Prisma Studio to create a user
npx prisma studio

4. Configure Environment

Copy .env.example to .env and update with your Claude Code token:

cp .env.example .env
# Edit .env and add your CLAUDE_CODE_OAUTH_TOKEN

5. Run Application

# Development mode
npm run start:dev

# Production mode
npm run build
npm run start:prod

Docker Production Deployment

Deploy taskrun using the official Docker image from Docker Hub. Supports both AMD64 (x86_64) and ARM64 (Apple Silicon, AWS Graviton) architectures.

Pull the Image

# Latest version
docker pull filipeai/taskrun:latest

# Specific version
docker pull filipeai/taskrun:1.0.0

Run with External PostgreSQL and Redis

docker run -p 7890:7890 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/taskrun" \
  -e REDIS_URL="redis://host:6379" \
  -e JWT_SECRET="your-secret-key-min-32-chars" \
  -e API_KEY_SECRET="your-api-key-secret" \
  -e TASKRUN_API_KEY="your-global-api-key" \
  -e CLAUDE_CODE_OAUTH_TOKEN="your-claude-token" \
  -e TASKRUN_API_URL="https://your-domain.com" \
  filipeai/taskrun:latest

Required Environment Variables

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string
• JWT_SECRET - Secret for JWT signing (min 32 chars)
• API_KEY_SECRET - Secret for API key hashing (min 32 chars)
• TASKRUN_API_KEY - Global API key for authentication (recommended)
• CLAUDE_CODE_OAUTH_TOKEN - Claude Code OAuth token
• TASKRUN_API_URL - Public URL where taskrun is accessible

Optional Environment Variables

• GEMINI_API_KEY - Google Gemini API key (for Gemini adapter)
• PORT - Internal backend port (default: 3000)
• CORS_ORIGINS - Allowed CORS origins (default: *)

Access Points

The container exposes port 7890 with:

• Frontend: http://localhost:7890/
• API: http://localhost:7890/api/v1/
• Health Check: http://localhost:7890/api/v1/health

Multi-Architecture Support

The Docker image is built for both architectures:

• linux/amd64 - Intel/AMD processors
• linux/arm64 - Apple Silicon (M1/M2/M3), AWS Graviton, ARM servers

Docker automatically pulls the correct architecture for your platform.

API Usage

Authentication

taskrun supports two authentication methods:

1. Global API Key (Recommended for Docker/Self-Hosted)

Set TASKRUN_API_KEY in your .env file:

TASKRUN_API_KEY="your-global-api-key-here"

This single key will work for all API requests. Perfect for Docker deployments and self-hosted installations.

2. Per-User Database Keys (Optional)

For multi-user scenarios, create users via Prisma Studio:

npx prisma studio
# Navigate to User model and create users with individual API keys

Submit a Task

curl -X POST http://localhost:3000/v1/tasks \
  -H "Authorization: Bearer your-global-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "List all TypeScript files in this project",
    "agent": {
      "description": "File lister agent",
      "systemPrompt": "You are a helpful assistant that lists files using the Glob tool.",
      "model": "claude-sonnet-4",
      "allowedTools": ["Glob", "Read"],
      "maxTurns": 10,
      "permissionMode": "auto"
    },
    "options": {
      "priority": "high"
    }
  }'

Stream Progress (Real-Time)

curl -N http://localhost:3000/v1/tasks/<taskId>/stream

Get Task Status

curl http://localhost:3000/v1/tasks/<taskId> \
  -H "Authorization: Bearer tsk_YOUR_API_KEY"

Environment Variables

Variable	Description	Default
TASKRUN_API_KEY	Global API key for all requests (recommended)	Optional
CLAUDE_CODE_OAUTH_TOKEN	Claude Code SDK token (from claude setup-token)	Required
DATABASE_URL	PostgreSQL connection string	postgresql://taskrun:taskrun_dev_password@localhost:5433/taskrun
REDIS_URL	Redis connection string	redis://localhost:6380
API_KEY_SECRET	Secret for hashing per-user API keys	Required (min 32 chars)
JWT_SECRET	Secret for JWT signing	Required (min 32 chars)
PORT	Server port	3000
NODE_ENV	Environment mode	development

Architecture

REST API → Task Management → Queue (BullMQ) → Claude Code Adapter → Claude Code SDK
                ↓
         Database (Prisma)
                ↓
         SSE Streaming (Real-time)

Key Components

• API Layer: NestJS controllers with validation
• Authentication: API key system with HMAC-SHA256
• Queue: BullMQ with Redis for async task processing
• Adapter: Claude Code SDK integration with message normalization
• Storage: PostgreSQL with Prisma ORM
• Streaming: Server-Sent Events for real-time progress

Docker Compose Services

• PostgreSQL - Port 5433 (external) → 5432 (internal)
• Redis - Port 6380 (external) → 6379 (internal)

Non-default ports are used to avoid conflicts with other services.

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:cov

Project Status

✅ Production-Ready Foundation

• Real Claude Code SDK integration
• Full authentication system
• Async task queue with priority
• Real-time SSE streaming
• TypeScript strict mode
• 25 tests passing

See IMPLEMENTATION_STATUS.md for complete details.

Documentation

• docs/OVERVIEW.md - Vision and core concepts
• docs/ARCHITECTURE.md - System design
• docs/TECHNICAL.md - Implementation guide
• docs/API.md - REST API reference
• docs/TEMPLATES.md - Agent templates guide
• IMPLEMENTATION_STATUS.md - Current implementation status

License

Apache 2.0 - Copyright 2025 Filipe Labs LTDA

Force rebuild Tue Oct 28 12:44:27 UTC 2025