This release is a pre-release and may not be stable for production use.
🤖 Zrb: Your Automation Powerhouse
Zrb (Zaruba) is a Python-based tool that makes it easy to create, organize, and run automation tasks. Think of it as a command-line sidekick, ready to handle everything from simple scripts to complex, AI-powered workflows.
Whether you're running tasks from the terminal or a sleek web UI, Zrb streamlines your process with task dependencies, environment management, and even inter-task communication.
Contribution Guidelines | Report an Issue
📑 Table of Contents
- 🔥 Why Choose Zrb?
- 🚀 Quickstart Part 1: Your First Basic Pipeline
- 🚀 Quickstart Part 2: AI-Powered Workflow
- 🖥️ Try the Web UI
- 💬 Interact with an LLM Directly
- 🧩 Program Your AI Agent
- ⚙️ Installation & Configuration
- 🤝 CI/CD Integration
- 🗺️ Documentation Directory
- 🎥 Demo Video
- 💖 Support Zrb
- 🎉 Fun Fact
🔥 Why Choose Zrb?
Zrb is designed to be powerful yet intuitive, offering a unique blend of features:
- 🤖 A Coding Agent You Program in Python: Zrb ships a turnkey AI coding assistant (
zrb llm chat), but its behavior is yours to shape in pure Python — custom tools, lifecycle hooks, dynamic prompts, permission policies, and history processors are all just code. And the agent drops straight into your task pipelines as a first-class node. - 🔗 Agents as Pipeline Steps: Put an LLM between deterministic tasks for bounded, reviewable automation instead of treating the model as an unattended administrator. Keep approvals, sandboxing, hooks, and persistence under your control.
- 🐍 Pure Python: Write your tasks in Python. No complex DSLs or YAML configurations to learn.
- 🔗 Smart Task Chaining: Define dependencies between tasks to build sophisticated, ordered workflows.
- 💻 Dual-Mode Execution: Run tasks from the command line for speed or use the built-in web UI for a more visual experience.
- ⚙️ Flexible Configuration: Manage inputs with defaults, prompts, or command-line arguments. Handle secrets and settings with environment variables from the system or
.envfiles. - 🗣️ Cross-Communication (XCom): Allow tasks to safely exchange small pieces of data.
- 🌍 Open & Extensible: Zrb is open-source. Feel free to contribute, customize, or extend it to meet your needs.
🚀 Quickstart Part 1: Your First Basic Pipeline in < 2 Minutes
Let's start with the absolute basics: defining simple units of work and chaining them together. You only need Python installed.
1. Define Your Tasks
Create a file named zrb_init.py in your project directory (or your home directory for global access!).
# zrb_init.py
from zrb import cli, CmdTask, Task
# 1. Define tasks.
# CmdTask is perfect for running shell commands.
prepare_env = CmdTask(
name="prepare-env",
cmd="echo 'Environment prepared!'"
)
# Task is for pure Python logic.
build_app = Task(
name="build-app",
action=lambda ctx: ctx.print("Building application in pure Python...")
)
deploy_app = CmdTask(
name="deploy-app",
cmd="echo 'Deploying app to the cloud ☁️'"
)
# 2. Register tasks to the main 'cli' object so Zrb knows about them
cli.add_task(prepare_env)
cli.add_task(build_app)
cli.add_task(deploy_app)
# 3. Define the execution order (The Directed Acyclic Graph - DAG)
# prepare-env runs first, then build-app, then deploy-app
prepare_env >> build_app >> deploy_app
2. Run Your First Pipeline!
Now, open your terminal and run:
zrb deploy-app
Zrb will see that deploy-app depends on build-app, which depends on prepare-env. It will automatically run them in the correct sequential order:
[prepare-env] Environment prepared!
[build-app] Building application in pure Python...
[build-app] Build complete.
[deploy-app] Deploying app to the cloud ☁️
Congratulations! You've just built and run your first Zrb automation pipeline.
🚀 Quickstart Part 2: Your First AI-Powered Workflow in < 5 Minutes
Now that you understand the basics, let's unleash Zrb's full power. This example uses an LLM to analyze your code and generate a Mermaid diagram, then converts that diagram into a PNG image.
1. Prerequisites
- An LLM API Key: Zrb needs an API key to talk to an AI model (OpenAI is default, but others are supported).
export OPENAI_API_KEY="your-key-here"
- Mermaid CLI: This tool converts Mermaid diagram scripts into images. Install it via npm:
npm install -g @mermaid-js/mermaid-cli
2. Update Your zrb_init.py
Add the following to your existing zrb_init.py file (or create a new one if you prefer to keep examples separate):
# zrb_init.py (continued)
from zrb import cli, LLMTask, CmdTask, StrInput, Group
from zrb.llm.tool.code import analyze_code
from zrb.llm.tool.file import write_file
# Create a group for Mermaid-related tasks
mermaid_group = cli.add_group(Group(
name="mermaid",
description="🧜 Mermaid diagram related tasks"
))
# Task 1: Generate a Mermaid script from your source code using an LLM
make_mermaid_script = mermaid_group.add_task(
LLMTask(
name="make-script",
description="Create a mermaid diagram from source code in the current directory",
input=[
StrInput(name="dir", default="./"),
StrInput(name="diagram", default="state-diagram"),
],
message=(
"Read all necessary files in {ctx.input.dir}, "
"make a {ctx.input.diagram} in mermaid format. "
"Write the script into `{ctx.input.dir}/{ctx.input.diagram}.mmd`"
),
tools=[analyze_code, write_file],
)
)
# Task 2: Convert the Mermaid script into a PNG image using CmdTask
make_mermaid_image = mermaid_group.add_task(
CmdTask(
name="make-image",
description="Create a PNG from a mermaid script",
input=[
StrInput(name="dir", default="./"),
StrInput(name="diagram", default="state-diagram"),
],
cmd="mmdc -i '{ctx.input.diagram}.mmd' -o '{ctx.input.diagram}.png'",
cwd="{ctx.input.dir}",
)
)
# Set up the dependency: the image task runs after the script is created
make_mermaid_script >> make_mermaid_image
3. Run Your AI-Powered Workflow!
Navigate to any project with source code (e.g., a Python project). For instance, if you've cloned a repository:
git clone https://github.com/someuser/my-python-project.git
cd my-python-project
Now, run your new task:
zrb mermaid make-image
Zrb will interactively ask for the directory and diagram name. Just press Enter to accept the defaults (./ and state-diagram). The AI will analyze your code, generate the Mermaid script, and mmdc will convert it to a PNG. In moments, you'll have a beautiful diagram of your code!
🖥️ Try the Web UI
Prefer a graphical interface? Zrb has you covered. Explore the full details in the Web UI Guide.
zrb server start
By default, the server binds to 127.0.0.1, so the UI is reachable only from the local machine. Then open your browser to http://localhost:21213 to see your tasks in a clean, user-friendly interface.
Safety boundary: Zrb's web UI can start and control automation tasks, so it is not intended to be exposed publicly without deliberate hardening. If you set
ZRB_WEB_HTTP_HOSTto a non-loopback address, enable authentication and replace the documented default admin password and secret key with unique values. Startup warnings call out unsafe network-exposed configurations; see the Web UI Guide before using a shared or public bind.
💬 Interact with an LLM Directly
Zrb brings AI capabilities right to your command line. For full details on configuring and using the AI assistant, see the LLM Integration Guide.
Interactive Chat
Start a chat session with an LLM to ask questions, brainstorm ideas, or get coding help.
zrb llm chat
🧩 Program Your AI Agent
zrb llm chat works out of the box — but the moment you need it to do something specific, you don't reach for a config file or a separate SDK. You write Python, in the same file where you define the rest of your automation.
Every part of the agent is a value you can supply or a callable you can register:
| You want to… | You write a… |
|---|---|
| Give the agent abilities | custom tool — a plain Python function it can call in-process |
| React to what it does | lifecycle hook — fires on tool calls, prompts, session start/end |
| Gate dangerous actions | permission policy / async approval channel |
| Inject live context into the prompt | dynamic prompt section — a lambda ctx: ... evaluated per request |
| Keep long conversations affordable | history processor — prune, redact, or summarize the message history |
| Route by cost or task | a model callable — pick the model per request |
Example: a custom tool the agent calls in-process
from zrb import cli, LLMChatTask
# A normal Python function becomes a tool — typed args + docstring are the spec.
async def get_open_incidents(team: str) -> str:
"""Return the current open incidents for a given team."""
return my_oncall_db.query(team) # your code, running in-process
chat = LLMChatTask(name="ops-chat", tools=[get_open_incidents])
cli.add_task(chat)
The part nothing else does: the agent is a pipeline node
Because an LLMTask is just a Zrb task, you can wire it between deterministic steps. Its answer flows downstream through XCom, and your tools can call straight into your codebase:
fetch_ticket >> triage_with_llm >> route_to_team
👉 Full walkthrough and every hook in one place: Programming the Agent. Runnable example: examples/agent-in-pipeline.
⚙️ Installation & Configuration
Ready to dive deeper into getting Zrb set up and customized? Our comprehensive guides cover everything you need:
- Installation Guide: Details on
pipinstall, the automatedinstall.shscript, Docker images, and even running Zrb on Android (Termux/Proot). - Environment Variables & Overrides: An exhaustive list of all general environment variables to customize Zrb's behavior.
- LLM & Rate Limiter Configuration: Everything you need to configure your LLM provider, manage token budgets, and fine-tune AI behavior.
🤝 CI/CD Integration
Integrate Zrb into your Continuous Integration/Continuous Deployment pipelines for robust, automated workflows. See the CI/CD Integration Guide for examples with GitHub Actions, GitLab CI, and Bitbucket Pipelines.
🗺️ Documentation Directory
Zrb scales from simple scripts to massive automation ecosystems. Explore the documentation to unlock its full potential.
New here? Read these three in order, then branch out as needed: Tasks & Execution Lifecycle → CLI and Groups → Inputs. Prefer learning by copy-pasting a working example? See
examples/instead.
docs/adr/anddocs/technical-specs/are maintainer-facing design history, not part of the reading path below.
I. Core Concepts
The foundational pillars of the framework.
- Tasks & Execution Lifecycle
- CLI and Groups
- Inputs
- Environments (Envs)
- Session, Context & XCom
- The
@make_taskDecorator — (advanced) full parameter reference - XCom Deep Dive — (advanced) patterns & pitfalls
II. Task Types
All task types available in Zrb, from basic to advanced.
- Task & CmdTask — Python actions and shell commands
- Custom Tasks — subclassing
BaseTaskwith async patterns - Readiness: HttpCheck & TcpCheck
- Automation: Triggers & Schedulers
- File Ops: Scaffolder & RsyncTask
- Built-in Helper Tasks (Git, Base64, UUID, HTTP, etc.)
III. LLM & AI Integration
- Choosing Between Agent Harnesses — zrb
llm chatvs Claude Code, opencode, DeepSeek Harness, and Pi: when each is the right tool - Programming the Agent — the overview: every way to shape agent behavior in Python (tools, hooks, dynamic prompts, history processors, agent-as-pipeline-node)
- Programming the Prompt — the ladder from a plain-string
messageup to a composedPromptManager; feeding aCmdTask's output intoLLMTask/LLMChatTask - LLM Assistant & AI Tasks — interactive chat,
LLMTask/LLMChatTaskusage, troubleshooting - Extending the LLM — built-in tools, custom tools, sub-agents, model capabilities, context management
- Custom UI — build a TUI, web/SSE, or chat-bot front end for
LLMChatTask - Permission Policy System — fine-grained tool control & security gates
- Sandbox — filesystem containment for LLM tool calls
- Plan Mode — read-only discovery & strategy phase
- LLMChatTask API Reference — builder API, TUI configuration
- LLM Chat Request Lifecycle — end-to-end tour: CLI → agent run → UI → history persistence
- Hook System (Claude Code Compatible)
- MCP Support (Model Context Protocol)
- LSP Support (Language Server Protocol)
- Technical Spec: LLM Journal System
- Claude Code Compatibility
IV. Advanced Topics
- Web UI Guide
- White-labeling: Create a Custom CLI
- CI/CD Integration
- Logging — Python logging vs. task-level context logging
- Testing Zrb Tasks — mocking context, testing pipelines
- Upgrading Guide
V. Contributing
- Which pattern do I reach for? — lookup table for the pattern zrb expects when adding new code
- Architecture & Conventions — for maintainers and contributors
- Framework Conventions — the enforced R1–R12 rules
- Maintainer Guide — start here to contribute code
VI. Configuration
- Environment Variables & Overrides
- LLM & Rate Limiter Configuration
- LLM Component Collections — registries, managers, and the three configuration channels for skills, agents, hooks, prompts, and tools
VII. Examples
examples/— runnablezrb_init.pyfor every topic above, grouped by category
VIII. Changelog
- Changelog — full release history
🎥 Demo Video
Watch a video demonstration of Zrb in action:
💖 Support Zrb
If you find Zrb valuable, please consider showing your support:
🎉 Fun Fact
Did you know? Zrb is named after Zaruba, a powerful, sentient Madou Ring that acts as a guide and support tool in the Garo universe.
Madou Ring Zaruba (魔導輪ザルバ, Madōrin Zaruba) is a Madougu which supports bearers of the Garo Armor. (Garo Wiki | Fandom)
1 maintainer
Release files for zrb 3.0.0b2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| zrb-3.0.0b2.tar.gz | 2.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| zrb-3.0.0b2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.9 MB
Release files / zrb-3.0.0b2.tar.gz
| Download URL | zrb-3.0.0b2.tar.gz |
|---|---|
| Size | 2.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d86a25e2a9738fd5a231de1cc6df664ead1de8f87e24dd6d8474cdca50fb6fb6
|
|
BLAKE2b-256 checksum How to use checksums |
fa80e3681ffb925a0d9ab4cd010d7f187ca681b40395dbc9f9ccfdb7491ded52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.3 CPython/3.14.0 Linux/5.15.153.1-microsoft-standard-WSL2+
|
Release files / zrb-3.0.0b2-py3-none-any.whl
| Download URL | zrb-3.0.0b2-py3-none-any.whl |
|---|---|
| Size | 2.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f61c0cee5ec93c40666b01b8bc0d645a579015e7a4b7947af74425007fce857
|
|
BLAKE2b-256 checksum How to use checksums |
567fa6d29ed1bcf52b828ddbfae0a8a0de4d408432defae132a74398dfac0d62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.3 CPython/3.14.0 Linux/5.15.153.1-microsoft-standard-WSL2+
|
