orb-py 1.8.3

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

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

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

See the Configuration Guide for path resolution details, environment variables, and REST API server 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

See the AWS Provider Guide for required IAM permissions and SpotFleet service-linked role 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

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.

All available commands and flags.

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

See the CLI Reference for the full flag reference.

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"

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.

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"]
    }
  }
}

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

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.

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

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.

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.

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.

• 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