orb-py 1.5.2

Open Resource Broker (ORB) — dynamic cloud resource provisioning via CLI and REST API

Unified API for orchestrating and provisioning compute capacity

---

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, Python SDK, or MCP server.

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

Provider support:

• AWS — EC2 RunInstances, EC2Fleet, SpotFleet, Auto Scaling Groups
• Custom — extensible via provider registry

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> ...

Setup

Get ORB installed and configured for your environment.

Installation

Standard install

pip install orb-py

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

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

Interfaces

ORB provides four ways to interact with your infrastructure.

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 system serve.

# 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"

Python SDK

Async-first programmatic access via ORBClient.

from orb import ORBClient as orb

async with orb(provider="aws") as sdk:
    # List templates
    templates = await sdk.list_templates(active_only=True)

    # Request machines
    request = await sdk.request_machines(
        template_id=templates[0]["template_id"],
        count=3
    )

    # Check status
    status = await sdk.get_request_status(request_id=request["created_request_id"])

See the SDK Quickstart for the full guide.

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/awslabs/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

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/awslabs/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: awslabs.github.io/open-resource-broker

---

License

Apache License 2.0 — see LICENSE.

Security

See SECURITY.md for responsible disclosure procedures.