Installation & Setup#

Get OSPREY running in five steps. The whole process takes about 10 minutes.

What you’ll have when done

  • Node.js, Claude Code, and uv installed

  • An API key configured for your AI provider

  • The osprey CLI installed and on your PATH

  • The ability to create projects with osprey build

Step 1: Install Node.js#

Claude Code requires Node.js 18+.

brew install node

If you don’t have Homebrew, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or use your distribution's package manager

Install Node.js inside your WSL2 environment:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify:

node --version
# You should see v18.x.x or higher

Step 2: Install Claude Code#

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

Step 3: Install Python tools#

OSPREY uses uv for fast Python package management. It handles Python versions and virtual environments automatically.

brew install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

Step 4: Set up your API key#

Claude Code needs an API key for the AI provider. Set it in your shell profile so it’s always available.

CBORG is the LBNL AI proxy. If you don’t have a key yet, sign up at https://api.cborg.lbl.gov.

echo 'export CBORG_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

Replace your-key-here with your actual key. To verify:

echo $CBORG_API_KEY

Get an API key from https://console.anthropic.com/.

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

OSPREY supports 100+ providers via LiteLLM. Set the appropriate key:

# OpenAI
export OPENAI_API_KEY="sk-..."

# Google
export GOOGLE_API_KEY="..."

See Configure LLM Providers for the full list.

Note

Using bash instead of zsh? Replace ~/.zshrc with ~/.bashrc.

Step 5: Install OSPREY#

Install OSPREY as a standalone CLI tool. uv creates an isolated environment for OSPREY and puts the osprey command on your PATH.

uv tool install osprey-framework

This is the right choice for most users. Your own projects stay separate from the tool — you’ll create them in their own directories with osprey build.

To upgrade later:

uv tool upgrade osprey-framework

Clone the repository if you want to pin to a specific git ref, track main for unreleased changes, or contribute back to OSPREY.

git clone https://github.com/als-apg/osprey.git
cd osprey
uv sync --extra dev

This creates a .venv inside the clone with OSPREY installed in editable mode plus dev dependencies. Commands in the rest of the docs that show osprey ... should be run as uv run osprey ... from inside the clone, or activate the venv with source .venv/bin/activate.

Verify:

osprey --version

OSPREY versions follow the YYYY.MM.MICRO CalVer scheme — the first two segments identify the release window, the micro segment increments for hotfixes. See CHANGELOG.md for details.

You’re done! 🎉#

OSPREY is installed and ready to use. Here’s what to do next:

Hello World Tutorial

Build your first agent with a mock control system. One MCP server, zero complexity. Takes about 10 minutes.

Hello World Tutorial
Guided Build Interview

Set OSPREY up for your own detector, beamline, or accelerator subsystem. A guided conversation generates a ready-to-build project profile tailored to your system. Takes about 10–15 minutes.

Guided Project Setup
Advanced: Container runtime, services & detailed configuration

The steps above cover the core installation. The following are only needed for specific use cases.

Container Runtime (Docker or Podman)

A container runtime is only required if you plan to deploy containerized services (Jupyter, simulation IOCs, databases). The core agent workflow does not require containers.

Download from the Docker website and verify:

docker --version
docker compose version

Install from the Podman website and verify:

podman --version

On macOS/Windows, also run:

podman machine init
podman machine start

Deploying Services

See Container Deployment for setting up containerized services like Jupyter notebooks, databases, or simulation IOCs.

Detailed Configuration

See Configure LLM Providers for provider setup and Build Profiles for the full build profile YAML reference.

Troubleshooting#

Common issues
“claude: command not found”

Install Claude Code: npm install -g @anthropic-ai/claude-code

“osprey: command not found”

If you installed via uv tool install osprey-framework, make sure uv’s tool bin directory is on your PATH — run uv tool update-shell once and open a new terminal. If you installed from source, either activate the venv (source .venv/bin/activate) or prefix commands with uv run from inside the clone.

MCP connection failed

Ensure you’re running claude from your project root where .mcp.json lives.

Provider authentication error

Check that your API key is exported: echo $CBORG_API_KEY (or whichever key you’re using). Re-source your shell profile if needed: source ~/.zshrc

Python version mismatch

OSPREY requires Python 3.11+. Check with python3 --version. The uv tool can install the right version automatically.

Verification checklist:

node --version       # Should be 18+
claude --version     # Should print version
uv --version         # Should print version
osprey --version     # Should print version