Quickstart

Run the self-hosted editor locally, define a node with the Python SDK, and sync it into the visual workspace.

Prerequisites

• Python 3.11 or newer for the backend
• Python 3.13 or newer for the published Python SDK
• Node.js 22 or newer and pnpm

Install the application

git clone https://github.com/Orchetree/Orchetree.git
cd Orchetree

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

cd src/frontend
pnpm install

Run the editor

Start the backend from the repository root:

source .venv/bin/activate
PYTHONPATH=src .venv/bin/uvicorn backend.main:app --port 8000 --reload

Start the frontend in another terminal:

cd src/frontend
pnpm dev

Open http://localhost:5173.

Define a Python node

Install the SDK in a Python 3.13 environment:

pip install orchetree

Create agents.py:

import orchetree


@orchetree.node(
    tree="Content Pipeline",
    capability="synthesis",
    business_prompt="Summarise the provided content into five key points.",
    system_prompt="Preserve factual claims and flag ambiguity.",
)
def summarise(inputs: dict) -> dict:
    return inputs

Sync the decorated definition:

orchetree sync --url http://localhost:8000 --project-id 1 --dir .

The SDK registers structure and prompts. Tree execution happens in the Orchetree backend using the AI connection selected for each node.

Connect a hosted provider

Open Settings > AI Connections and add a provider key. For low-cost cloud testing, see Hosted providers.

Export a bundle

Use the editor export action or the REST endpoint:

curl -H "X-Orchetree-Role: developer" \
  "http://localhost:8000/api/v1/export/project/1" \
  --output project.bundle.json

The Python and Node SDK CLIs currently provide init, sync, and watch. They do not provide an export command.

Where to go next

Use the documentation as a workflow rather than a flat reference:

1. Read Product tour to understand the Projects page, tree editor, Showcase Project, Settings, and Runs area.
2. Learn the data model in Core concepts, then configure nodes, prompt blocks, connectors, and skills.
3. Add and assign a model in AI connections. For hosted trial options, see Hosted providers.
4. Follow Execution, Runs and traces, and Versions and rollback to test and govern a system.
5. Use the Python SDK or Node.js SDK for code-first authoring.
6. Integrate through the API or expose trees through MCP and bundles.
7. Choose self-hosting or review the managed cloud boundary before deployment.