---
name: bijection-orchestrator
description: "Evaluate and integrate the Orchestrator component with Bijection."
---

# Orchestrator

A Bijection orchestrator component for Bijection.

- Package: @bijectionhq/orchestrator
- Category: AI & Agents
- Status: Reference
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/orchestrator/tree/fc8a0457434cf9f2b810fb6956648f97a70aac55
- Upstream: https://github.com/AkshatGiri/convex-orchestrator/tree/68427d858c542256b5d502cb7e044a0acec8779d
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/orchestrator

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/orchestrator.git
cd orchestrator
git checkout fc8a0457434cf9f2b810fb6956648f97a70aac55
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @akshatgiri/convex-orchestrator. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# convex-orchestrator

## Instructions

A durable workflow orchestration system built on Convex that executes step functions on your local machines while storing workflow state durably. Workers pull workflow tasks from Convex, execute activities locally, and record results with automatic leasing and heartbeat mechanisms. Provides workflow primitives like durable sleep, signals, and step execution with replay safety.

### Installation

```bash
npm install @akshatgiri/convex-orchestrator
```

## Use cases

- **Multi-step user onboarding flows** that need to survive server restarts, like sending welcome emails, waiting for verification, then provisioning access
- **Long-running approval workflows** where you need to pause execution until human approval signals are received
- **Data processing pipelines** with multiple dependent steps that require durability and the ability to resume from failure points
- **Scheduled reminder systems** that send emails or notifications after specific time delays, with replay-safe sleep mechanisms
- **Complex business processes** that involve external API calls, waiting periods, and conditional logic that must be resilient to worker crashes

## How it works

The component stores workflow state in Convex (`workflows` and `steps` tables) while actual step execution happens on worker machines that pull tasks from Convex. You define workflows using the `workflow()` function and `ctx.step()` for durable operations, then run workers locally using `createWorker()` with your workflow definitions.

Workers use a leasing system with heartbeats to claim workflows and prevent duplicate execution. If a worker dies, another can reclaim the workflow and resume from the last completed step. The `ctx.step()` calls are replay-safe - successful results are stored durably and returned on subsequent replays.

Durable primitives include `ctx.sleep()` for time-based delays and `ctx.waitForSignal()` for external events, both using stable markers to ensure replay safety. You expose the component's API through your Convex app using `exposeApi()` and `exposeApiWithWorker()`, with the latter requiring authorization for production use.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by convex-orchestrator is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40akshatgiri%2Fconvex-orchestrator)
- [GitHub repository](https://github.com/akshatgiri/convex-orchestrator)
- [Convex Components Directory](https://www.convex.dev/components/akshatgiri/convex-orchestrator)
- [Convex documentation](https://docs.convex.dev)