🚀 Getting Started with Sloth Runner¶

Welcome to Sloth Runner - the AI-powered GitOps task orchestration platform! This guide will get you up and running in minutes.

📦 Installation¶

Quick Install (Recommended)¶

Install the latest release with our automated script:

curl -sSL https://raw.githubusercontent.com/chalkan3-sloth/sloth-runner/main/install.sh | bash

This script: - ✅ Detects your OS and architecture automatically - ✅ Downloads the latest release from GitHub - ✅ Installs to /usr/local/bin - ✅ Verifies installation

Note: Requires sudo privileges.

Manual Installation¶

Download from GitHub Releases:

# Linux AMD64
wget https://github.com/chalkan3-sloth/sloth-runner/releases/latest/download/sloth-runner-linux-amd64.tar.gz
tar xzf sloth-runner-linux-amd64.tar.gz
sudo mv sloth-runner /usr/local/bin/

# macOS ARM64 (Apple Silicon)
wget https://github.com/chalkan3-sloth/sloth-runner/releases/latest/download/sloth-runner-darwin-arm64.tar.gz
tar xzf sloth-runner-darwin-arm64.tar.gz
sudo mv sloth-runner /usr/local/bin/

Verify Installation¶

sloth-runner version

🎯 Quick Start¶

Your First Workflow¶

Create a simple workflow file hello.sloth:

-- hello.sloth
task("hello")
  :description("My first task")
  :command(function()
    print("🦥 Hello from Sloth Runner!")
    return true
  end)
  :build()

Run it:

sloth-runner run -f hello.sloth

Modern Output Styles¶

Try different output formats:

# Basic output
sloth-runner run -f hello.sloth -o basic

# Enhanced with colors and icons
sloth-runner run -f hello.sloth -o enhanced

# Rich with progress bars
sloth-runner run -f hello.sloth -o rich

# Modern UI
sloth-runner run -f hello.sloth -o modern

# JSON for CI/CD
sloth-runner run -f hello.sloth -o json

📚 Core Concepts¶

File Extension¶

📝 Important: Sloth Runner uses .sloth extension for workflow files (not .lua). The syntax is still Lua - only the extension changed for better identification.

Tasks¶

Tasks are the building blocks. Define with the builder pattern:

task("build")
  :description("Build the application")
  :command("go build -o app")
  :build()

task("test")
  :description("Run tests")
  :command("go test ./...")
  :depends_on("build")
  :build()

Task Groups¶

Organize related tasks:

task_group("ci")
  :description("CI pipeline")
  :tasks({"build", "test", "lint"})

🗂️ Stack Management¶

Stacks provide state persistence and environment isolation.

Create a Stack¶

sloth-runner stack new prod-app \
  -f deploy.sloth \
  --description "Production deployment"

Run with Stack¶

# Run workflow on stack
sloth-runner run prod-app --yes

# Check stack state
sloth-runner stack show prod-app

# List all stacks
sloth-runner stack list

Stack Benefits¶

✅ State persistence between runs
✅ Environment isolation
✅ History tracking
✅ Resource management

🎨 Modern DSL Features¶

Task Builder API¶

task("deploy")
  :description("Deploy to production")
  :condition(function() return os.getenv("ENV") == "prod" end)
  :command(function()
    log.info("Deploying...")
    return exec.run("kubectl apply -f k8s/")
  end)
  :on_success(function()
    log.success("✅ Deployed successfully!")
  end)
  :on_error(function(err)
    log.error("❌ Deployment failed: " .. err)
  end)
  :timeout(300)
  :retry(3)
  :build()

Values Files¶

Parameterize workflows with values files:

values.yaml:

environment: production
replicas: 3
image: myapp:v1.2.3

deploy.sloth:

local env = values.environment
local replicas = values.replicas

task("deploy")
  :command(function()
    log.info("Deploying to " .. env)
    log.info("Replicas: " .. replicas)
  end)
  :build()

Run with values:

sloth-runner run -f deploy.sloth -v values.yaml

🤖 Built-in Modules¶

Sloth Runner includes powerful built-in modules:

Example: Docker Deployment¶

local docker = require("docker")

task("deploy_container")
  :command(function()
    -- Pull image
    docker.pull("nginx:latest")

    -- Run container
    docker.run({
      image = "nginx:latest",
      name = "web-server",
      ports = {"80:80"},
      detach = true
    })

    return true
  end)
  :build()

Available Modules¶

🐳 docker - Container management
☁️ aws, azure, gcp - Cloud providers
🔧 systemd - Service management
📦 pkg - Package management
📊 metrics - Monitoring
🔐 vault - Secrets management
🌍 terraform - Infrastructure as Code

See all modules →

🎭 Common Workflows¶

CI/CD Pipeline¶

task("lint")
  :command("golangci-lint run")
  :build()

task("test")
  :command("go test -v ./...")
  :depends_on("lint")
  :build()

task("build")
  :command("go build -o app")
  :depends_on("test")
  :build()

task("deploy")
  :command(function()
    exec.run("docker build -t myapp .")
    exec.run("docker push myapp")
    exec.run("kubectl rollout restart deployment/myapp")
  end)
  :depends_on("build")
  :build()

Run the pipeline:

sloth-runner run -f pipeline.sloth -o rich

Infrastructure Automation¶

local terraform = require("terraform")

task("plan")
  :command(function()
    return terraform.plan({
      dir = "./terraform",
      var_file = "prod.tfvars"
    })
  end)
  :build()

task("apply")
  :command(function()
    return terraform.apply({
      dir = "./terraform",
      auto_approve = true
    })
  end)
  :depends_on("plan")
  :build()

🌐 Distributed Execution¶

Start Master Server¶

sloth-runner master --port 50053 --daemon

Start Agents¶

On different servers:

# Web server agent
sloth-runner agent start \
  --master master.example.com:50053 \
  --name web-01 \
  --tags web,nginx

# Database agent  
sloth-runner agent start \
  --master master.example.com:50053 \
  --name db-01 \
  --tags database,postgres

Distribute Tasks¶

task("deploy_web")
  :target_agent("web-01")
  :command("nginx -s reload")
  :build()

task("backup_db")
  :target_agent("db-01")
  :command("pg_dump mydb > backup.sql")
  :build()

📊 Web Dashboard¶

Start the UI for visual management:

sloth-runner ui --port 8080

Access at: http://localhost:8080

Features: - 📈 Real-time task monitoring - 🤖 Agent health dashboard - 📅 Scheduler management - 📦 Stack browser - 📊 Metrics and analytics

🔄 Scheduler¶

Schedule recurring tasks:

-- In your workflow
schedule("nightly_backup")
  :cron("0 2 * * *")  -- 2 AM daily
  :task("backup")
  :build()

Manage from CLI:

# Enable scheduler
sloth-runner scheduler enable

# List scheduled tasks
sloth-runner scheduler list

# Disable scheduler
sloth-runner scheduler disable

💡 Tips & Best Practices¶

1. Use Stacks for State Management¶

# ✅ Good: Use stacks
sloth-runner stack new myapp
sloth-runner run myapp

# ❌ Avoid: Direct execution without state
sloth-runner run -f workflow.sloth

2. Choose the Right Output Format¶

# Interactive terminal
sloth-runner run -f deploy.sloth -o rich

# CI/CD pipelines
sloth-runner run -f ci.sloth -o json

# Simple scripts
sloth-runner run -f task.sloth -o basic

3. Use Values Files for Environments¶

# Development
sloth-runner run -f app.sloth -v dev-values.yaml

# Production
sloth-runner run -f app.sloth -v prod-values.yaml

4. Leverage Built-in Modules¶

-- ❌ Don't shell out unnecessarily
task("install"):command("apt-get install nginx"):build()

-- ✅ Use built-in modules
local pkg = require("pkg")
task("install"):command(function()
  return pkg.install("nginx")
end):build()

📖 Next Steps¶

Now that you're started, explore more:

📘 Core Concepts - Deep dive into architecture
🎨 Modern DSL - Advanced syntax
🔧 CLI Reference - All commands
📦 Modules - Built-in capabilities
🎭 Examples - Real-world workflows
🤖 AI Features - Intelligent optimization
🚀 GitOps - Automated deployments

🆘 Getting Help¶

📖 Documentation: Full docs
💬 Community: GitHub Discussions
🐛 Issues: Bug Reports
📝 Examples: Example Repository

Ready to automate? Create your first workflow and start orchestrating! 🚀

English | Português | 中文