Skip to content

๐Ÿš€ 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

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
local hello_task = task("hello")
  :description("My first task")
  :command(function(this, params)
    print("๐Ÿฆฅ Hello from Sloth Runner!")
    return true, "Task completed successfully"
  end)
  :build()

workflow
  .define("hello_workflow")
  :description("Hello world workflow")
  :version("1.0.0")
  :tasks({hello_task})

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:

local build_task = task("build")
  :description("Build the application")
  :command(function(this, params)
    return exec.run("go build -o app")
  end)
  :build()

local test_task = task("test")
  :description("Run tests")
  :depends_on({"build"})
  :command(function(this, params)
    return exec.run("go test ./...")
  end)
  :build()

workflow
  .define("ci_pipeline")
  :description("CI pipeline")
  :version("1.0.0")
  :tasks({build_task, test_task})

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

local deploy_task = task("deploy")
  :description("Deploy to production")
  :command(function(this, params)
    -- Check environment condition
    if os.getenv("ENV") ~= "prod" then
      return false, "Not in production environment"
    end

    log.info("Deploying...")
    local success, output = exec.run("kubectl apply -f k8s/")

    if success then
      log.info("โœ… Deployed successfully!")
    else
      log.error("โŒ Deployment failed: " .. output)
    end

    return success, output
  end)
  :timeout("5m")
  :retries(3)
  :build()

workflow
  .define("deployment")
  :description("Production deployment")
  :version("1.0.0")
  :tasks({deploy_task})

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

local deploy_task = task("deploy")
  :description("Deploy application")
  :command(function(this, params)
    log.info("Deploying to " .. env)
    log.info("Replicas: " .. replicas)
    return true, "Deployment configuration applied"
  end)
  :build()

workflow
  .define("deploy_workflow")
  :description("Deploy with values")
  :version("1.0.0")
  :tasks({deploy_task})

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")

local deploy_container = task("deploy_container")
  :description("Deploy nginx container")
  :command(function(this, params)
    -- Pull image
    docker.pull("nginx:latest")

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

    return true, "Container deployed successfully"
  end)
  :build()

workflow
  .define("docker_deploy")
  :description("Deploy Docker container")
  :version("1.0.0")
  :tasks({deploy_container})

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

local lint_task = task("lint")
  :description("Run linter")
  :command(function(this, params)
    return exec.run("golangci-lint run")
  end)
  :build()

local test_task = task("test")
  :description("Run tests")
  :depends_on({"lint"})
  :command(function(this, params)
    return exec.run("go test -v ./...")
  end)
  :build()

local build_task = task("build")
  :description("Build application")
  :depends_on({"test"})
  :command(function(this, params)
    return exec.run("go build -o app")
  end)
  :build()

local deploy_task = task("deploy")
  :description("Deploy application")
  :depends_on({"build"})
  :command(function(this, params)
    exec.run("docker build -t myapp .")
    exec.run("docker push myapp")
    exec.run("kubectl rollout restart deployment/myapp")
    return true, "Deployment completed"
  end)
  :build()

workflow
  .define("cicd_pipeline")
  :description("Complete CI/CD pipeline")
  :version("1.0.0")
  :tasks({lint_task, test_task, build_task, deploy_task})

Run the pipeline:

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

Infrastructure Automation

local plan_task = task("plan")
  :description("Plan Terraform changes")
  :command(function(this, params)
    return terraform.plan({
      dir = "./terraform",
      var_file = "prod.tfvars"
    })
  end)
  :build()

local apply_task = task("apply")
  :description("Apply Terraform changes")
  :depends_on({"plan"})
  :command(function(this, params)
    return terraform.apply({
      dir = "./terraform",
      auto_approve = true
    })
  end)
  :build()

workflow
  .define("terraform_deploy")
  :description("Terraform deployment")
  :version("1.0.0")
  :tasks({plan_task, apply_task})

๐ŸŒ 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

local deploy_web = task("deploy_web")
  :description("Reload nginx")
  :delegate_to("web-01")
  :command(function(this, params)
    return exec.run("nginx -s reload")
  end)
  :build()

local backup_db = task("backup_db")
  :description("Backup database")
  :delegate_to("db-01")
  :command(function(this, params)
    return exec.run("pg_dump mydb > backup.sql")
  end)
  :build()

workflow
  .define("distributed_ops")
  :description("Distributed operations")
  :version("1.0.0")
  :tasks({deploy_web, backup_db})

๐Ÿ“Š 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
local install_bad = task("install")
  :description("Install nginx (bad)")
  :command(function(this, params)
    return exec.run("apt-get install nginx")
  end)
  :build()

-- โœ… Use built-in modules
local install_good = task("install")
  :description("Install nginx (good)")
  :command(function(this, params)
    return pkg.install({packages = {"nginx"}})
  end)
  :build()

๐Ÿ“– Next Steps

Now that you're started, explore more:

๐Ÿ†˜ Getting Help

Ready to automate? Create your first workflow and start orchestrating! ๐Ÿš€

English | Portuguรชs | ไธญๆ–‡