# Orcheo

[![CI](https://github.com/ShaojieJiang/orcheo/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/ShaojieJiang/orcheo/actions/workflows/ci.yml?query=branch%3Amain)
[![Coverage](https://coverage-badge.samuelcolvin.workers.dev/ShaojieJiang/orcheo.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/ShaojieJiang/orcheo)
[![PyPI - Core](https://img.shields.io/pypi/v/orcheo.svg?logo=python&label=core)](https://pypi.org/project/orcheo/)
[![PyPI - Backend](https://img.shields.io/pypi/v/orcheo-backend.svg?logo=python&label=backend)](https://pypi.org/project/orcheo-backend/)
[![PyPI - SDK](https://img.shields.io/pypi/v/orcheo-sdk.svg?logo=python&label=sdk)](https://pypi.org/project/orcheo-sdk/)
[![PyPI - Agentensor](https://img.shields.io/pypi/v/agentensor.svg?logo=python&label=agentensor)](https://pypi.org/project/agentensor/)
[![npm - Canvas](https://img.shields.io/npm/v/orcheo-canvas.svg?logo=npm&label=canvas)](https://www.npmjs.com/package/orcheo-canvas)

Orcheo is a workflow orchestration platform designed for vibe coding — AI coding agents like Claude Code can start services, build workflows, and deploy them for you automatically.

> **Note:** This project is currently in Beta. Expect breaking changes as we iterate rapidly towards 1.0.

> **SIGIR Reviewers:** See the **[Conversational Search Examples](https://orcheo.readthedocs.io/en/latest/conversational_search_examples/)** for step-by-step demos from basic RAG to production-ready search.

## Why Orcheo?

- **Vibe-coding-first**: Already using Claude Code, Codex CLI, or Cursor? You **don't** need to learn Orcheo. Install the [agent skill](https://github.com/ShaojieJiang/agent-skills) and let your AI agent handle setup, workflow creation, and deployment.
- **Python-native**: Workflows are Python code powered by LangGraph — no proprietary DSL to learn.
- **Backend-first**: Run headless in production; the UI is optional.

## Prerequisites

- **Docker** — for running Redis and other services
- **Python 3.12+** — required for the backend
- **uv** — Python package manager ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))

## Quick Start

The fastest way to get started with Orcheo is through the **Agent Skill** approach — let your AI coding agent handle the setup for you.

> **Note:** Most AI coding agents (Claude Code, Codex CLI, Cursor) require a paid subscription. Free alternatives may exist but have not been tested with Orcheo.

### 1. Install the Orcheo Agent Skill

Add the [Orcheo agent skill](https://github.com/ShaojieJiang/agent-skills) to your AI coding agent (Claude Code, Cursor, etc.) by following the installation instructions in the repo.

### 2. Let Your Agent Do the Work

Once installed, simply ask your agent to:

- **Set up Orcheo**: "Set up Orcheo for local development"
- **Create workflows**: "Create a workflow that monitors RSS feeds and sends Slack notifications"
- **Deploy workflows**: "Deploy and schedule my workflow to run every hour"

Your AI agent will automatically:
- Install dependencies
- Start the backend server
- Create and configure workflows
- Handle authentication and deployment

That's it! Your agent handles the complexity while you focus on describing what you want your workflows to do.

## Guides

- **[Manual Setup Guide](https://orcheo.readthedocs.io/en/latest/manual_setup/)** — Installation, CLI reference, authentication, and Canvas setup
- **[Conversational Search Examples](https://orcheo.readthedocs.io/en/latest/conversational_search_examples/)** — Step-by-step demos from basic RAG to production-ready search

```bash
# Quick start: Run Demo 1 (no external services required)
uv sync --group examples
orcheo credential create openai_api_key --secret sk-your-key
python examples/conversational_search/demo_2_basic_rag/demo_2.py
```

## Reference

- **[SDK Reference](https://orcheo.readthedocs.io/en/latest/sdk_reference/)** — Python SDK for programmatic workflow execution
- **[Environment Variables](https://orcheo.readthedocs.io/en/latest/environment_variables/)** — Complete configuration reference

## For Developers

- **[Developer Guide](https://orcheo.readthedocs.io/en/latest/manual_setup/#developer-guide)** — Repository layout, development environment, and custom nodes
- **[Deployment Guide](https://orcheo.readthedocs.io/en/latest/deployment/)** — Docker Compose and PostgreSQL deployment recipes
- **[Custom Nodes and Tools](https://orcheo.readthedocs.io/en/latest/custom_nodes_and_tools/)** — Extend Orcheo with your own integrations

## Contributing

We welcome contributions from the community:

- **Share your extensions**: Custom nodes, agent tools, and workflows that extend Orcheo's capabilities. See the [Custom Nodes and Tools guide](https://orcheo.readthedocs.io/en/latest/custom_nodes_and_tools/) for how to create and load custom extensions.
- **How to contribute**: Open an [issue](https://github.com/ShaojieJiang/orcheo/issues), submit a [pull request](https://github.com/ShaojieJiang/orcheo/pulls), or start a [discussion](https://github.com/ShaojieJiang/orcheo/discussions). You can also publish and share your extensions independently for others to install.

## Citation

If you use Orcheo in your research, please cite it as:

```bibtex
@software{jiang2025orcheo,
  author       = {Jiang, Shaojie},
  title        = {Orcheo: A Workflow Orchestration Platform for Vibe Coding},
  year         = {2025},
  publisher    = {GitHub},
  url          = {https://github.com/ShaojieJiang/orcheo}
}
```
