Run#

Execute predefined sequences of shell commands directly from your lokio/configs.yaml.

What is `lokio run`?#

lokio run lets you define runbooks — named sequences of shell steps — inside your project's config file and execute them with a single command. Think of it as a lightweight task runner built into Lokio: no separate Makefile, no shell scripts to maintain.

Common uses:

Setting up a fresh server (install Docker, Nginx, PostgreSQL, etc.)
Bootstrapping a dev environment
Running deploy sequences
Automating repetitive system tasks shared across the team

Basic Usage #

lokio run --id <id>

Examples:

lokio run --id install-docker
lokio run --id setup-vm
lokio run --id install-nodejs

Configuration #

Runs are defined in the runs: section of lokio/configs.yaml.

runs:
  - id: install-docker
    description: Install Docker & Docker Compose (Ubuntu/Debian)
    steps:
      - name: Update apt
        run: sudo apt update -y
      - name: Install Docker Engine
        run: sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
      - name: Add user to docker group
        run: sudo usermod -aG docker $USER
      - name: Verify Docker
        run: docker --version && docker compose version

Run fields #

Field	Required	Description
`id`	yes	Unique identifier — used with `lokio run --id <id>`
`description`	yes	Human-readable description of what the run does
`steps`	yes	List of steps to execute sequentially

Step fields #

Field	Required	Description
`name`	yes	Label displayed while the step is running
`run`	yes	Shell command(s) to execute
`continue_on_error`	no	If `true`, continue to the next step even if this one fails

Multi-line Commands #

Use the YAML block scalar (|) for commands that span multiple lines:

steps:
  - name: Add Docker GPG key
    run: |
      sudo install -m 0755 -d /etc/apt/keyrings
      curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
        | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
      sudo chmod a+r /etc/apt/keyrings/docker.gpg
  - name: Add Docker repo
    run: |
      echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
        https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
        | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

`continue_on_error`#

By default, a run stops immediately if any step fails. Set continue_on_error: true on a step to let the run continue regardless:

steps:
  - name: Run Redis container
    run: docker run -d --name redis --restart unless-stopped -p 6379:6379 redis:7-alpine
    continue_on_error: true   # container may already exist — that's fine
  - name: Verify Redis
    run: docker exec redis redis-cli ping

This is useful when a step may fail non-fatally — for example, starting a container that is already running, or cleaning up a resource that might not exist.

Example Output #

  Running: install-docker

  ● Update apt
  ✓ Update apt

  ● Install Docker Engine
  ✓ Install Docker Engine

  ● Add user to docker group
  ✓ Add user to docker group

  ● Verify Docker
  ✓ Verify Docker

  ✓ Done — 4 step(s) completed

If a step fails:

  ● Install Docker Engine
  ✗ Install Docker Engine — exit code 1

  Run stopped. Fix the error above and try again.

With continue_on_error: true:

  ● Run Redis container
  ⚠ Run Redis container — exit code 125 (skipped, continue_on_error: true)

  ● Verify Redis
  ✓ Verify Redis

Real-World Examples #

Install Node.js via NVM #

- id: install-nodejs
  description: Install Node.js LTS via NVM
  steps:
    - name: Install NVM
      run: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    - name: Install Node.js LTS
      run: |
        export NVM_DIR="$HOME/.nvm"
        [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
        nvm install --lts && nvm use --lts && nvm alias default 'lts/*'
    - name: Install pnpm
      run: |
        export NVM_DIR="$HOME/.nvm"
        [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
        npm install -g pnpm
    - name: Verify
      run: |
        export NVM_DIR="$HOME/.nvm"
        [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
        node -v && npm -v && pnpm -v

lokio run --id install-nodejs

Full VM Setup #

Combine multiple installs into a single run:

- id: setup-vm
  description: Full server setup — Docker, PostgreSQL, Redis, Node.js, Nginx, UFW
  steps:
    - name: Update & upgrade system
      run: sudo apt update -y && sudo apt upgrade -y
    - name: Install base utils
      run: sudo apt install -y curl wget git unzip htop net-tools ufw build-essential
    - name: Install Docker
      run: |
        sudo install -m 0755 -d /etc/apt/keyrings
        curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
          | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
        sudo chmod a+r /etc/apt/keyrings/docker.gpg
        echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
          https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
          | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
        sudo apt update -y && sudo apt install -y docker-ce docker-ce-cli containerd.io
        sudo usermod -aG docker $USER
    - name: Install Nginx
      run: sudo apt install -y nginx && sudo systemctl enable --now nginx
    - name: Setup UFW
      run: |
        sudo ufw allow OpenSSH
        sudo ufw allow 80/tcp && sudo ufw allow 443/tcp
        sudo ufw --force enable
    - name: Summary
      run: |
        docker --version
        nginx -v
        sudo ufw status

lokio run --id setup-vm

Tips #

Source shell config inside steps — each step runs in its own subprocess, so ~/.bashrc / ~/.zshrc is not automatically loaded. Load the needed env explicitly:

- name: Use NVM
  run: |
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
    nvm use --lts

Keep steps focused — one logical action per step makes the output readable and errors easy to pinpoint.

Use description — it's displayed in lokio run --help and makes the runbook self-documenting for teammates.

Run

Run#

What is lokio run?##

Basic Usage##

Configuration##

Run fields##

Step fields##

Multi-line Commands##

continue_on_error##

Example Output##

Real-World Examples##

Install Node.js via NVM##

Full VM Setup##

Tips##

See Also##