Spaces:
Running
Running
| title: Lobster | |
| summary: "Typed workflow runtime for OpenClaw with resumable approval gates." | |
| description: Typed workflow runtime for OpenClaw — composable pipelines with approval gates. | |
| read_when: | |
| - You want deterministic multi-step workflows with explicit approvals | |
| - You need to resume a workflow without re-running earlier steps | |
| # Lobster | |
| Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints. | |
| ## Hook | |
| Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state. | |
| ## Why | |
| Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime: | |
| - **One call instead of many**: OpenClaw runs one Lobster tool call and gets a structured result. | |
| - **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved. | |
| - **Resumable**: Halted workflows return a token; approve and resume without re-running everything. | |
| ## Why a DSL instead of plain programs? | |
| Lobster is intentionally small. The goal is not "a new language," it's a predictable, AI-friendly pipeline spec with first-class approvals and resume tokens. | |
| - **Approve/resume is built in**: A normal program can prompt a human, but it can’t _pause and resume_ with a durable token without you inventing that runtime yourself. | |
| - **Determinism + auditability**: Pipelines are data, so they’re easy to log, diff, replay, and review. | |
| - **Constrained surface for AI**: A tiny grammar + JSON piping reduces “creative” code paths and makes validation realistic. | |
| - **Safety policy baked in**: Timeouts, output caps, sandbox checks, and allowlists are enforced by the runtime, not each script. | |
| - **Still programmable**: Each step can call any CLI or script. If you want JS/TS, generate `.lobster` files from code. | |
| ## How it works | |
| OpenClaw launches the local `lobster` CLI in **tool mode** and parses a JSON envelope from stdout. | |
| If the pipeline pauses for approval, the tool returns a `resumeToken` so you can continue later. | |
| ## Pattern: small CLI + JSON pipes + approvals | |
| Build tiny commands that speak JSON, then chain them into a single Lobster call. (Example command names below — swap in your own.) | |
| ```bash | |
| inbox list --json | |
| inbox categorize --json | |
| inbox apply --json | |
| ``` | |
| ```json | |
| { | |
| "action": "run", | |
| "pipeline": "exec --json --shell 'inbox list --json' | exec --stdin json --shell 'inbox categorize --json' | exec --stdin json --shell 'inbox apply --json' | approve --preview-from-stdin --limit 5 --prompt 'Apply changes?'", | |
| "timeoutMs": 30000 | |
| } | |
| ``` | |
| If the pipeline requests approval, resume with the token: | |
| ```json | |
| { | |
| "action": "resume", | |
| "token": "<resumeToken>", | |
| "approve": true | |
| } | |
| ``` | |
| AI triggers the workflow; Lobster executes the steps. Approval gates keep side effects explicit and auditable. | |
| Example: map input items into tool calls: | |
| ```bash | |
| gog.gmail.search --query 'newer_than:1d' \ | |
| | openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}' | |
| ``` | |
| ## JSON-only LLM steps (llm-task) | |
| For workflows that need a **structured LLM step**, enable the optional | |
| `llm-task` plugin tool and call it from Lobster. This keeps the workflow | |
| deterministic while still letting you classify/summarize/draft with a model. | |
| Enable the tool: | |
| ```json | |
| { | |
| "plugins": { | |
| "entries": { | |
| "llm-task": { "enabled": true } | |
| } | |
| }, | |
| "agents": { | |
| "list": [ | |
| { | |
| "id": "main", | |
| "tools": { "allow": ["llm-task"] } | |
| } | |
| ] | |
| } | |
| } | |
| ``` | |
| Use it in a pipeline: | |
| ```lobster | |
| openclaw.invoke --tool llm-task --action json --args-json '{ | |
| "prompt": "Given the input email, return intent and draft.", | |
| "input": { "subject": "Hello", "body": "Can you help?" }, | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "intent": { "type": "string" }, | |
| "draft": { "type": "string" } | |
| }, | |
| "required": ["intent", "draft"], | |
| "additionalProperties": false | |
| } | |
| }' | |
| ``` | |
| See [LLM Task](/tools/llm-task) for details and configuration options. | |
| ## Workflow files (.lobster) | |
| Lobster can run YAML/JSON workflow files with `name`, `args`, `steps`, `env`, `condition`, and `approval` fields. In OpenClaw tool calls, set `pipeline` to the file path. | |
| ```yaml | |
| name: inbox-triage | |
| args: | |
| tag: | |
| default: "family" | |
| steps: | |
| - id: collect | |
| command: inbox list --json | |
| - id: categorize | |
| command: inbox categorize --json | |
| stdin: $collect.stdout | |
| - id: approve | |
| command: inbox apply --approve | |
| stdin: $categorize.stdout | |
| approval: required | |
| - id: execute | |
| command: inbox apply --execute | |
| stdin: $categorize.stdout | |
| condition: $approve.approved | |
| ``` | |
| Notes: | |
| - `stdin: $step.stdout` and `stdin: $step.json` pass a prior step’s output. | |
| - `condition` (or `when`) can gate steps on `$step.approved`. | |
| ## Install Lobster | |
| Install the Lobster CLI on the **same host** that runs the OpenClaw Gateway (see the [Lobster repo](https://github.com/openclaw/lobster)), and ensure `lobster` is on `PATH`. | |
| If you want to use a custom binary location, pass an **absolute** `lobsterPath` in the tool call. | |
| ## Enable the tool | |
| Lobster is an **optional** plugin tool (not enabled by default). | |
| Recommended (additive, safe): | |
| ```json | |
| { | |
| "tools": { | |
| "alsoAllow": ["lobster"] | |
| } | |
| } | |
| ``` | |
| Or per-agent: | |
| ```json | |
| { | |
| "agents": { | |
| "list": [ | |
| { | |
| "id": "main", | |
| "tools": { | |
| "alsoAllow": ["lobster"] | |
| } | |
| } | |
| ] | |
| } | |
| } | |
| ``` | |
| Avoid using `tools.allow: ["lobster"]` unless you intend to run in restrictive allowlist mode. | |
| Note: allowlists are opt-in for optional plugins. If your allowlist only names | |
| plugin tools (like `lobster`), OpenClaw keeps core tools enabled. To restrict core | |
| tools, include the core tools or groups you want in the allowlist too. | |
| ## Example: Email triage | |
| Without Lobster: | |
| ``` | |
| User: "Check my email and draft replies" | |
| → openclaw calls gmail.list | |
| → LLM summarizes | |
| → User: "draft replies to #2 and #5" | |
| → LLM drafts | |
| → User: "send #2" | |
| → openclaw calls gmail.send | |
| (repeat daily, no memory of what was triaged) | |
| ``` | |
| With Lobster: | |
| ```json | |
| { | |
| "action": "run", | |
| "pipeline": "email.triage --limit 20", | |
| "timeoutMs": 30000 | |
| } | |
| ``` | |
| Returns a JSON envelope (truncated): | |
| ```json | |
| { | |
| "ok": true, | |
| "status": "needs_approval", | |
| "output": [{ "summary": "5 need replies, 2 need action" }], | |
| "requiresApproval": { | |
| "type": "approval_request", | |
| "prompt": "Send 2 draft replies?", | |
| "items": [], | |
| "resumeToken": "..." | |
| } | |
| } | |
| ``` | |
| User approves → resume: | |
| ```json | |
| { | |
| "action": "resume", | |
| "token": "<resumeToken>", | |
| "approve": true | |
| } | |
| ``` | |
| One workflow. Deterministic. Safe. | |
| ## Tool parameters | |
| ### `run` | |
| Run a pipeline in tool mode. | |
| ```json | |
| { | |
| "action": "run", | |
| "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage", | |
| "cwd": "/path/to/workspace", | |
| "timeoutMs": 30000, | |
| "maxStdoutBytes": 512000 | |
| } | |
| ``` | |
| Run a workflow file with args: | |
| ```json | |
| { | |
| "action": "run", | |
| "pipeline": "/path/to/inbox-triage.lobster", | |
| "argsJson": "{\"tag\":\"family\"}" | |
| } | |
| ``` | |
| ### `resume` | |
| Continue a halted workflow after approval. | |
| ```json | |
| { | |
| "action": "resume", | |
| "token": "<resumeToken>", | |
| "approve": true | |
| } | |
| ``` | |
| ### Optional inputs | |
| - `lobsterPath`: Absolute path to the Lobster binary (omit to use `PATH`). | |
| - `cwd`: Working directory for the pipeline (defaults to the current process working directory). | |
| - `timeoutMs`: Kill the subprocess if it exceeds this duration (default: 20000). | |
| - `maxStdoutBytes`: Kill the subprocess if stdout exceeds this size (default: 512000). | |
| - `argsJson`: JSON string passed to `lobster run --args-json` (workflow files only). | |
| ## Output envelope | |
| Lobster returns a JSON envelope with one of three statuses: | |
| - `ok` → finished successfully | |
| - `needs_approval` → paused; `requiresApproval.resumeToken` is required to resume | |
| - `cancelled` → explicitly denied or cancelled | |
| The tool surfaces the envelope in both `content` (pretty JSON) and `details` (raw object). | |
| ## Approvals | |
| If `requiresApproval` is present, inspect the prompt and decide: | |
| - `approve: true` → resume and continue side effects | |
| - `approve: false` → cancel and finalize the workflow | |
| Use `approve --preview-from-stdin --limit N` to attach a JSON preview to approval requests without custom jq/heredoc glue. Resume tokens are now compact: Lobster stores workflow resume state under its state dir and hands back a small token key. | |
| ## OpenProse | |
| OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep, then run a Lobster pipeline for deterministic approvals. If a Prose program needs Lobster, allow the `lobster` tool for sub-agents via `tools.subagents.tools`. See [OpenProse](/prose). | |
| ## Safety | |
| - **Local subprocess only** — no network calls from the plugin itself. | |
| - **No secrets** — Lobster doesn't manage OAuth; it calls OpenClaw tools that do. | |
| - **Sandbox-aware** — disabled when the tool context is sandboxed. | |
| - **Hardened** — `lobsterPath` must be absolute if specified; timeouts and output caps enforced. | |
| ## Troubleshooting | |
| - **`lobster subprocess timed out`** → increase `timeoutMs`, or split a long pipeline. | |
| - **`lobster output exceeded maxStdoutBytes`** → raise `maxStdoutBytes` or reduce output size. | |
| - **`lobster returned invalid JSON`** → ensure the pipeline runs in tool mode and prints only JSON. | |
| - **`lobster failed (code …)`** → run the same pipeline in a terminal to inspect stderr. | |
| ## Learn more | |
| - [Plugins](/plugin) | |
| - [Plugin tool authoring](/plugins/agent-tools) | |
| ## Case study: community workflows | |
| One public example: a “second brain” CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like `weekly-review`, `inbox-triage`, `memory-consolidation`, and `shared-task-sync`, each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not. | |
| - Thread: https://x.com/plattenschieber/status/2014508656335770033 | |
| - Repo: https://github.com/bloomedai/brain-cli | |