Cyrus Cloudflare Container Integration

A Cloudflare Workers-based container orchestration system for AI-powered development environments. This integration enables Cyrus (or any AI agent) to work in isolated, containerized environments with full development capabilities.

🌟 Features

• Isolated Development Environments: Each Linear issue gets its own containerized environment
• Full Development Stack: Pre-configured with Node.js, Git, pnpm, and Claude Code CLI
• Linear Integration: OAuth authentication and webhook-based automation
• Automatic Lifecycle Management: Containers are created when issues are assigned and cleaned up when closed
• Command Execution: Execute commands in containers via API or Linear comments
• Persistent State: KV storage for container metadata and R2 for logs/artifacts

🏗️ Architecture

graph TD
    A[Linear Issue] -->|Webhook| B[Cloudflare Worker]
    B --> C[Container Manager]
    C --> D[Cloudflare Container]
    D --> E[Development Environment]
    B --> F[KV Storage]
    B --> G[R2 Bucket]
    H[Cyrus/AI Agent] -->|API| B

Loading

📋 Requirements

Prerequisites

• Cloudflare Account with Workers Paid plan (required for Cloudflare Containers)
• Linear Account with OAuth application configured
• Anthropic API Key (optional, for Claude integration)
• Node.js 18+ and npm/pnpm installed locally
• Wrangler CLI for deployment

For Cyrus/AI Agent Usage

The AI agent (Cyrus) needs:

• Bash access to execute commands
• Wrangler CLI configured with Cloudflare credentials
• HTTP client (curl/fetch) for API calls
• Git for repository operations

🚀 Deployment Guide

Step 1: Clone and Configure

# Clone the repository
git clone https://github.com/shebashio/cyrus-cloudflare-public.git
cd cyrus-cloudflare-public

# Install dependencies
npm install

# Copy the example configuration
cp wrangler.toml.example wrangler.toml

Step 2: Set Up Cloudflare Resources

# Login to Cloudflare
npx wrangler login

# Create KV namespace
npx wrangler kv:namespace create "CONTAINER_STATE"
npx wrangler kv:namespace create "CONTAINER_STATE" --preview

# Create R2 bucket
npx wrangler r2 bucket create cyrus-container-storage

# Update wrangler.toml with the KV namespace IDs from the output above

Step 3: Configure Secrets

# Linear OAuth credentials
npx wrangler secret put LINEAR_CLIENT_ID
npx wrangler secret put LINEAR_CLIENT_SECRET
npx wrangler secret put LINEAR_WEBHOOK_SECRET

# Anthropic API key (for Claude integration)
npx wrangler secret put ANTHROPIC_API_KEY

Step 4: Deploy the Worker

# Build Docker container (local)
docker build -t cyrus-dev-container .

# Deploy to Cloudflare
npx wrangler deploy

Step 5: Configure Linear OAuth Application

1. Go to Linear Settings > API
2. Create a new OAuth application with:
   • Redirect URI: https://YOUR-WORKER.workers.dev/oauth/callback
   • Webhook URL: https://YOUR-WORKER.workers.dev/webhook/linear
   • Scopes: read, write
3. Enable webhook events for Issues and Comments
4. Save Client ID, Client Secret, and Webhook Secret

Step 6: Authorize the Application

Visit https://YOUR-WORKER.workers.dev/oauth/authorize to complete OAuth flow.

🔧 API Reference

Create Container

POST /container/create
{
  "issueId": "LINEAR-123",
  "repositoryUrl": "https://github.com/user/repo.git",
  "linearToken": "optional-token",
  "claudeToken": "optional-anthropic-key"
}

Execute Command

POST /container/execute
{
  "issueId": "LINEAR-123",
  "command": "pnpm install && pnpm test"
}

Get Container Status

GET /container/status?issueId=LINEAR-123

Cleanup Container

POST /container/cleanup
{
  "issueId": "LINEAR-123"
}

🤖 Cyrus Integration

How Cyrus Uses This System

1. Issue Assignment: When a Linear issue is assigned to Cyrus, a webhook triggers container creation
2. Container Provisioning: A dedicated container is spun up with the repository cloned
3. Development Work: Cyrus executes commands via the API:

   # Example: Cyrus running tests
   curl -X POST https://YOUR-WORKER.workers.dev/container/execute \
     -H "Content-Type: application/json" \
     -d '{"issueId": "D3D-1083", "command": "pnpm test"}'

4. Automatic Cleanup: Container is destroyed when the issue is closed

Required Cyrus Capabilities

For Cyrus to work with this system, ensure:

1. API Access: Cyrus must be able to make HTTP requests
2. Wrangler Access: For deployment updates

   npx wrangler deploy
   npx wrangler tail  # For debugging

3. Environment Variables: Set in Cyrus's environment

   export CLOUDFLARE_WORKER_URL="https://YOUR-WORKER.workers.dev"
   export LINEAR_TOKEN="your-linear-token"

Example Cyrus Workflow

// Cyrus creates a container for an issue
const response = await fetch(`${WORKER_URL}/container/create`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    issueId: 'D3D-1083',
    repositoryUrl: 'https://github.com/shebashio/cyrus.git',
    linearToken: process.env.LINEAR_TOKEN
  })
});

const { containerId, endpoint } = await response.json();

// Execute development commands
const result = await fetch(`${WORKER_URL}/container/execute`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    issueId: 'D3D-1083',
    command: 'git pull && pnpm install && pnpm test'
  })
});

📦 Container Environment

Each container includes:

• OS: Debian-based Linux
• Node.js: v20 (configurable)
• Package Managers: npm, pnpm
• Version Control: git (pre-configured)
• Build Tools: gcc, make, python3
• Claude Code CLI: For AI-powered development

Dockerfile Customization

Modify the Dockerfile to add tools:

# Add your custom tools
RUN apt-get update && apt-get install -y \
    your-tool-here \
    && rm -rf /var/lib/apt/lists/*

🔍 Monitoring and Debugging

View Worker Logs

npx wrangler tail

Check Container Status

curl https://YOUR-WORKER.workers.dev/container/status?issueId=LINEAR-123

Health Check

curl https://YOUR-WORKER.workers.dev/health

🔐 Security Considerations

• OAuth Tokens: Stored encrypted in KV with expiration
• Webhook Signatures: All webhooks are verified using HMAC
• Container Isolation: Each container runs in isolation
• Automatic Cleanup: Containers are destroyed after use
• Secret Management: Use Wrangler secrets, never commit credentials

📚 Documentation

• Linear OAuth Setup Guide
• GitOps Workflow
• Integration Guide

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - See LICENSE file for details

🆘 Support

• Issues: GitHub Issues
• Documentation: Check the /docs folder
• Cloudflare Docs: Cloudflare Containers

⚠️ Important Notes

1. Cloudflare Containers is in Beta: Features may change
2. Requires Workers Paid Plan: Free tier doesn't support containers
3. Rate Limits Apply: Check Cloudflare's current limits
4. Container Startup Time: Initial container creation may take 10-30 seconds

🎯 Use Cases

• AI-Powered Development: Enable AI agents to work in isolated environments
• Issue-Based Workflows: One container per Linear issue
• Automated Testing: Run tests in clean environments
• Collaborative Development: Multiple agents can work in the same container
• Sandboxed Experiments: Test changes without affecting production

---

Built with ❤️ for AI-powered development workflows