Skip to content

Quick Start Guide

Get up and running with the Open Resource Broker in minutes.

Prerequisites

  • Python 3.10 or higher
  • AWS credentials configured (~/.aws/credentials or an IAM instance profile)
  • IAM permissions for EC2, EC2Fleet, SpotFleet, and Auto Scaling — see the README for the full policy

Installation

Standard install

pip install orb-py

Development install

pip install -e ".[dev]"

Step 1: Initialize

Run orb init to create the configuration directory and set up your first provider.

By default, orb init runs interactively and discovers your AWS VPCs, subnets, and security groups:

orb init

For CI/CD pipelines or scripted environments, skip AWS discovery with --non-interactive:

orb init --non-interactive

You can also pass infrastructure details directly in non-interactive mode:

orb init --non-interactive \
  --region us-east-1 \
  --profile my-aws-profile \
  --subnet-ids subnet-0abc1234,subnet-0def5678 \
  --security-group-ids sg-0abc1234 \
  --fleet-role arn:aws:iam::123456789012:role/MySpotFleetRole

Step 2: Generate templates

Generate example templates for your configured provider:

orb templates generate

This writes template files to your ORB work directory. Templates are scoped to a provider type (e.g., AWS EC2Fleet, SpotFleet) and reusable across provider instances.

Step 3: List templates

Verify the templates loaded correctly:

orb templates list

For a more readable view:

orb templates list --format table

Step 4: Request machines

Copy a template ID from the output of orb templates list, then request machines:

orb machines request <template-id> 3

Or using flags:

orb machines request --template-id <template-id> --count 3

The command returns a request ID. Use --wait to block until machines are ready:

orb machines request aws-ec2fleet-basic 3 --wait --timeout 600

Step 5: Check request status

orb requests status req-abc123

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

Step 6: View infrastructure

Show what infrastructure ORB is configured to use:

orb infrastructure show

To scan your AWS account for available VPCs, subnets, and security groups:

orb infrastructure discover

Step 7: View configuration

orb config show

Returning machines

When you're done with machines, return them:

orb machines return i-0abc1234def567890 i-0def5678abc123456

Troubleshooting

AWS permissions error — verify your credentials are active: 

aws sts get-caller-identity

No templates loaded — re-run generate and check your provider config: 

orb templates generate
orb config show

System health check: 

orb system health --detailed

Next steps