What is Lobster?

+15 Mana ✨
OpenClaw Lobster Overview(DOCUMENTATION)OpenClaw Workflow Definitions(DOCUMENTATION)

Introduction

Lobster is OpenClaw's typed workflow shell that lets you define deterministic pipelines as data. Unlike general-purpose scripting where execution paths can vary unpredictably, Lobster workflows follow a strict sequence of typed steps with explicit inputs and outputs. This makes them auditable, reproducible, and safe for automated execution.

Key Concepts

  • Typed Workflow Shell: A shell environment where every step has defined input and output types
  • Deterministic Execution: Given the same inputs, a Lobster pipeline always produces the same outputs in the same order
  • Pipeline-as-Data: Workflows are defined as structured data (JSON/YAML), not imperative code
  • Auditability: Every step execution is logged with its inputs, outputs, and timing for full traceability
  • DSL over General-Purpose Code: Lobster deliberately limits expressiveness in exchange for predictability and safety

Real World Context

A fintech company needs to automate their compliance reporting pipeline. Each report requires gathering data from three APIs, transforming it, generating a PDF, and uploading it to a secure storage bucket. Using a general-purpose script, a network error could leave the pipeline in an inconsistent state. With Lobster, each step is atomic, the pipeline can resume from the last successful step, and every execution is fully auditable for regulatory compliance.

Deep Dive

Why a DSL?

General-purpose languages offer unlimited flexibility but introduce unpredictability. A Python script can take any execution path based on runtime conditions. Lobster deliberately constrains what you can express:

yaml
# Lobster workflow definition
name: compliance-report
version: 1.0.0
steps:
  - id: fetch-transactions
    type: http
    config:
      url: "https://api.bank.com/transactions"
      method: GET
  - id: transform-data
    type: transform
    input: $steps.fetch-transactions.json
    config:
      format: csv
  - id: generate-report
    type: tool
    input: $steps.transform-data.stdout
    config:
      tool: pdf-generator

This YAML defines a three-step pipeline. Each step has a type, explicit inputs referencing previous step outputs, and a configuration block. The pipeline cannot branch, loop, or execute arbitrary code. This constraint is the source of Lobster's determinism.

Pipeline-as-Data

Because workflows are data (JSON or YAML), they can be versioned, diffed, and reviewed like any other configuration:

json
{
  "name": "compliance-report",
  "version": "1.0.0",
  "steps": [
    {
      "id": "fetch-transactions",
      "type": "http",
      "config": {
        "url": "https://api.bank.com/transactions",
        "method": "GET"
      }
    }
  ]
}

This JSON representation is equivalent to the YAML above. The structured format means tools can parse, validate, and visualize workflows without executing them.

Determinism and Auditability

Every Lobster execution produces an audit log:

json
{
  "pipelineId": "compliance-report",
  "runId": "run-2026-02-20-001",
  "steps": [
    {
      "id": "fetch-transactions",
      "startedAt": "2026-02-20T10:00:00Z",
      "completedAt": "2026-02-20T10:00:02Z",
      "status": "success",
      "outputSize": 15234
    }
  ]
}

This audit log records exactly when each step ran, how long it took, and whether it succeeded. For regulated industries, this traceability is not optional but a requirement.

Common Pitfalls

  • Trying to add conditional logic to Lobster: Lobster is deliberately linear. If you need branching, split your workflow into multiple pipelines with an orchestrator that chooses which one to run.
  • Using Lobster for interactive tasks: Lobster is designed for batch processing. Tasks that require user input mid-execution should use regular agent sessions.
  • Confusing Lobster workflows with shell scripts: Despite being called a workflow shell, Lobster does not execute arbitrary shell commands. It runs typed steps.

Best Practices

  • Use Lobster for repeatable, multi-step processes where determinism and auditability matter.
  • Store workflow definitions in version control to track changes and enable code review.
  • Keep workflows focused on a single logical process rather than combining unrelated tasks.

Summary

  • Lobster is a typed workflow shell that defines deterministic pipelines as structured data
  • Workflows are defined in JSON or YAML with explicit step types, inputs, and outputs
  • The DSL deliberately limits expressiveness in exchange for predictability and safety
  • Every execution produces an audit log with full traceability
  • Use Lobster for repeatable batch processes where determinism matters
✓ Completed