Unified API for orchestrating and provisioning compute capacity

---

Open Resource Broker (ORB) is a unified API for orchestrating and provisioning compute capacity programmatically. Define what you need in a template, request it, track it, return it — through a CLI, REST API, MCP server, or native SDKs in six languages (Python, Go, TypeScript, Java, Kotlin, .NET).

Built for AWS today (EC2, Auto Scaling Groups, SpotFleet, EC2Fleet, Lambda MicroVMs), with an extensible provider system for adding new cloud backends.

Provider support:

• AWS — EC2 RunInstances, EC2Fleet, SpotFleet, Auto Scaling Groups, Lambda MicroVMs
• Kubernetes — Pod, Deployment, StatefulSet, Job (pip install "orb-py[k8s]"; see Kubernetes provider docs)
• Custom — extensible via provider registry and the orb.providers entry-point group

Scheduler support:

• HostFactory — runs as an IBM Spectrum Symphony provider plugin
• Standalone — direct usage without an external scheduler

Quick Start

pip install orb-py
orb init
orb templates generate

1. Pick a template

orb templates list

2. Request machines

orb machines request <template-id> 3

3. Check status

orb requests status <request-id>

4. Return machines when done

orb machines return <machine-id-1> <machine-id-2> ...

5. Check the return status

machines return prints a return-request id; check it the same way as step 3:

orb requests status <return-request-id>

Setup

Get ORB installed and configured for your environment.

Installation

Standard install (core only — no provider)

pip install orb-py

ORB boots cleanly with no provider registered. Any command that needs a provider will return a clear "no provider configured" error rather than an ImportError.

Per-provider install

pip install "orb-py[aws]"          # AWS provider (boto3 + botocore)
pip install "orb-py[k8s]"   # Kubernetes provider (kubernetes SDK)
pip install "orb-py[aws,cli]"      # AWS provider + colored CLI output
pip install "orb-py[aws,api]"      # AWS provider + REST API server
pip install "orb-py[monitoring-aws]"  # AWS provider + full monitoring stack
pip install "orb-py[all]"          # All providers + all features

Provider extras matrix

Use case	Install command
Core only (no provider)	pip install orb-py
AWS operator	pip install "orb-py[aws]"
Kubernetes operator	pip install "orb-py[k8s]"
AWS + Kubernetes	pip install "orb-py[aws,k8s]"
AWS + colored CLI	pip install "orb-py[aws,cli]"
AWS + REST API	pip install "orb-py[aws,api]"
AWS + monitoring	pip install "orb-py[monitoring-aws]"
Full (all providers + features)	pip install "orb-py[all]"

With colored CLI output

pip install "orb-py[cli]"

With REST API server

pip install "orb-py[api]"

With monitoring and observability

pip install "orb-py[monitoring]"

Full install (all extras)

pip install "orb-py[all]"

Requires Python 3.10+.

Configuration

orb init creates a config.json in a location based on your install type (virtualenv, user install, system install, or development checkout). Override with:

export ORB_CONFIG_DIR=/path/to/config

Variable	Description
ORB_ROOT_DIR	Set base directory for all subdirs (config, work, logs, health, scripts)
ORB_CONFIG_DIR	Override config directory path (takes precedence over ORB_ROOT_DIR)
ORB_WORK_DIR	Override work directory path (takes precedence over ORB_ROOT_DIR)
ORB_LOG_DIR	Override logs directory path (takes precedence over ORB_ROOT_DIR)
ORB_HEALTH_DIR	Override health directory path (takes precedence over ORB_ROOT_DIR)
ORB_LOG_LEVEL	Logging level: DEBUG, INFO, WARNING, ERROR

See the Configuration Guide for path resolution details, environment variables, and REST API server setup.

AWS Provider Setup

ORB uses boto3's standard credential chain — any method that works with the AWS CLI works with ORB.

# Verify your credentials are active
aws sts get-caller-identity

Supported credential methods: AWS CLI profiles, environment variables (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), IAM instance profiles, SSO (aws sso login), and credential process.

Supported resource types

Type	Description
RunInstances	Direct EC2 instance provisioning
EC2Fleet	Fleet provisioning with mixed instance types
SpotFleet	Cost-optimized spot instance fleets
AutoScalingGroup	Managed scaling groups
MicroVM	Isolated Lambda MicroVM sandboxes for untrusted code

See the AWS Provider Guide for required IAM permissions and SpotFleet service-linked role setup. See the MicroVM Provider Guide for Lambda MicroVM setup.

Kubernetes Provider Setup

ORB uses the standard Kubernetes client credential chain — any context that works with kubectl works with ORB. Running in-cluster, it auto-detects the mounted service account; running outside, it reads your KUBECONFIG and current context.

# Verify your context is active
kubectl config current-context

Supported credential methods: KUBECONFIG contexts, the default ~/.kube/config, and in-cluster service accounts (auto-detected). See provider discovery for the detection order.

Supported resource types

Type	Description
Pod	Single-pod provisioning
Deployment	Replica-managed stateless workloads
StatefulSet	Stable-identity stateful workloads
Job	Run-to-completion batch workloads

Install with pip install "orb-py[k8s]". Minimum RBAC is in docs/root/providers/k8s/rbac.yaml; see the Kubernetes Provider Guide for full setup.

Interfaces

ORB provides multiple ways to interact with your infrastructure — a CLI, a REST API, an MCP server, and native SDKs in six languages.

CLI Reference

All available commands and flags.

Command	Description
orb init	Initialize config and discover AWS infrastructure
orb init --non-interactive	Initialize without interactive prompts
orb templates generate	Generate example templates for your provider
orb templates list	List available templates
orb templates list --format table	Table view
orb templates show <template-id>	Show a single template
orb templates validate --file <file>	Validate a template file
orb machines request <template-id> <n>	Request n machines
orb machines list	List active machines
orb machines return <machine-id> [...]	Return one or more machines
orb requests status <request-id>	Check request status
orb requests list	List all requests
orb infrastructure show	Show configured infrastructure
orb infrastructure discover	Scan AWS for VPCs, subnets, security groups
orb infrastructure validate	Verify infrastructure still exists in AWS
orb config show	Show current configuration
orb config validate	Validate configuration
orb providers list	List configured providers
orb system health	System health check
orb system health --detailed	Detailed health check

Request status values: pending, in_progress, completed, failed, cancelled, partial, timeout.

See the CLI Reference for the full flag reference.

REST API

Example API calls. Requires pip install "orb-py[api]" and orb server start (add --foreground for an in-shell variant).

# Get available templates
curl -X GET "http://localhost:8000/api/v1/templates"

# Create machine request
curl -X POST "http://localhost:8000/api/v1/requests" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "my-template", "maxNumber": 5}'

# Check request status
curl -X GET "http://localhost:8000/api/v1/requests/req-12345"

SDKs (Python, Go, TypeScript, Java, Kotlin, .NET)

Native client libraries in six languages. Python is async-first and in-process; the other five drive a managed orb server over a local socket, so they share one OpenAPI contract and behave identically.

Language	Install	Entry point
Python	pip install orb-py	orb.ORBClient
Go	go get github.com/finos/open-resource-broker/sdk/go	orb.Client
TypeScript / Node	npm install @finos/open-resource-broker	OrbClient
Java	org.finos.openresourcebroker:open-resource-broker-java	OrbClient
Kotlin	org.finos.openresourcebroker:open-resource-broker-kotlin	OrbClient
.NET / C#	dotnet add package FINOS.OpenResourceBroker	OrbClient

from orb import ORBClient as orb

async with orb(provider="aws") as sdk:
    templates = await sdk.list_templates(active_only=True)
    request = await sdk.request_machines(
        template_id=templates["templates"][0]["template_id"],
        count=3,
    )
    status = await sdk.get_request_status(request_id=request["request_id"])

See the SDK documentation for per-language install and usage guides, the Python SDK Quickstart, and Generate Your Own SDK.

MCP Server (AI Assistant Integration)

ORB provides a Model Context Protocol (MCP) server for AI assistant integration:

# Start MCP server in stdio mode (for AI assistants)
orb mcp serve --stdio

# Start as TCP server (for development/testing)
orb mcp serve --port 3000 --host localhost

Available MCP Tools:

• Provider Management: check_provider_health, list_providers, get_provider_config
• Template Operations: list_templates, get_template, validate_template
• Infrastructure Requests: request_machines, get_request_status, return_machines

Available MCP Resources:

• templates:// — Available compute templates
• requests:// — Provisioning requests
• machines:// — Compute instances
• providers:// — Cloud providers

Claude Desktop Configuration:

{
  "mcpServers": {
    "open-resource-broker": {
      "command": "orb",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Integrations

Connect ORB to schedulers and container platforms.

HostFactory Integration

ORB integrates with IBM Spectrum Symphony as a HostFactory provider plugin, providing full API compatibility through shell scripts:

Script	Description
getAvailableTemplates.sh	List available compute templates
requestMachines.sh	Request new compute instances
getRequestStatus.sh	Poll request status
requestReturnMachines.sh	Return instances
getReturnRequests.sh	Check return request status

Scripts are available for both Linux (bash) and Windows (bat). They are generated automatically by orb init and placed in your config directory.

Key features:

• Full HostFactory API compatibility
• Automatic CPU and RAM attribute generation from AWS instance types
• Native HostFactory output format (camelCase JSON)
• Drop-in replacement for existing provider plugins

Example template output:

{
  "templates": [
    {
      "templateId": "t3-medium-template",
      "maxNumber": 5,
      "attributes": {
        "type": ["String", "X86_64"],
        "ncpus": ["Numeric", "2"],
        "nram": ["Numeric", "4096"]
      }
    }
  ]
}

See the HostFactory Guide for full integration details.

Docker Deployment

Run ORB as a containerized service.

git clone https://github.com/finos/open-resource-broker.git
cd open-resource-broker
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d
curl http://localhost:8000/health

Symphony HostFactory on Kubernetes (legacy)

The k8s-legacy module is a Symphony HostFactory custom provider plugin for Kubernetes, predating the modern multi-cloud ORB architecture. It is now bundled with orb-py as an optional install extra rather than as a separate PyPI package.

Install with:

pip install "orb-py[k8s-legacy]"

Confirm the install by listing available templates:

orb k8s-legacy get-available-templates

The plugin is in maintenance mode. A modern Kubernetes provider with native ORB integration is in development; existing deployments remain fully supported.

• Upgrading from open-resource-broker? See the migration guide.
• Deploying the Symphony HF plugin? See the k8s-legacy deployment guide.

Project

Architecture, development, and documentation.

Architecture

ORB is built on Clean Architecture with Domain-Driven Design (DDD) and CQRS:

• Domain layer — pure business logic, no infrastructure dependencies
• Application layer — command/query handlers using abstract ports
• Infrastructure layer — AWS adapters, DI container, storage strategies
• Interface layer — CLI, REST API, MCP server

The provider system uses a Strategy/Registry pattern — each cloud provider (AWS, future providers) registers its own strategy, handlers, and template format. The scheduler system uses the same pattern — HostFactory and Default schedulers are interchangeable strategies behind a common port.

See the Architecture Guide for details.

Development

Set up a local development environment.

git clone https://github.com/finos/open-resource-broker.git
cd open-resource-broker
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run the test suite:

make test

Lint and format:

make lint
make format

See CONTRIBUTING.md for the full development guide.

Documentation & CI

• Quick Start
• CLI Reference
• Configuration Guide
• Template Management
• Troubleshooting
• Architecture
• API Reference
• Deployment
• DeepWiki — AI-generated codebase documentation

Full docs: finos.github.io/open-resource-broker

---

License

Apache License 2.0 — see LICENSE.

Security

See SECURITY.md for responsible disclosure procedures.