How-To Guides#

Task-oriented guides that walk you through common OSPREY operations step by step. Each guide focuses on a single goal and assumes you already have a working OSPREY installation. The sections follow the natural journey: build and deploy a project, operate the agent day to day, then work with the bundled facility services.

Build & deploy#

Build Profiles

Build a facility-specific assistant from a profile you own — convention directories, taking ownership of framework artifacts, tiers, apps, and secrets.

Build Profiles
Deploy a Facility

The end-to-end walkthrough: one deployment repo from osprey init through the CI scaffolding to a running four-service stack.

Deploy a Facility
Container Deployment

The service stack behind a running project — compose templates, networking, the environment chain, and the agent’s own container image.

Container Deployment
LLM Providers

Pick the provider that drives the OSPREY agent and name the model it runs, including open-weight and self-hosted models behind the translation proxy.

LLM Providers
Build Your Own OSPREY Apps

A panel for the operator and tools for the agent over one backend: what an app is and how to make one.

Build Your Own OSPREY Apps
Register a Measurement Kind

Add a measurement of your own from an installable package: its declaration, its block in the measurement file, and what the build refuses.

Register a measurement kind

Operate#

Web Terminal

The browser cockpit for the OSPREY agent — launching and theming it, adding your own side panels, reporting problems from inside it, and serving a whole team from one host.

Web Terminal
Agent Interfaces

The CLI agent, event-driven dispatch, external MCP servers, and chat bridges — the four ways to reach the agent.

Agent Interfaces
Health and Monitoring

Is it up, and what is it doing — facility health checks you can extend, plus the agent record of what the agent was asked and did.

Health and Monitoring
Control Systems

Connectors for your control system, the virtual accelerator to rehearse on, switching to the live machine, and what the agent may not touch.

Control Systems
Safety Watchdogs

Have facility-written checks judge each operator prompt, hold the agent’s writes when one flags it, and ask the operator to stop or continue.

Safety watchdogs

Facility services#

Describe Your Facility

The source tree under data/facility/ — records, layers and importers, fixes, limits, seeds, models and measurement — that every facility service is built from.

Describe your facility
Measure with the pyAML Tools

Measure orbit, dispersion, tune and chromaticity responses on the control target, every write under the control target’s run lock, and read the model’s orbit response.

Measure with the pyAML tools
Use the Channel Finder

Search, filter, and explore control system channels using the Channel Finder service and its web interface, including every PV the control system announces.

How to Use the Channel Finder
Facility Knowledge

The Open Knowledge Format bundle, the facility graph, facility rules, and the search sidecar that serves all of it to the agent on demand.

Facility Knowledge
ARIEL Logbook Search

Search over facility electronic logbooks with keyword and semantic retrieval modes, plus multi-step reasoning delegated to the OSPREY agent.

Logbook Search Service (ARIEL)
Bluesky Plans

Run measurement plans through a durable queue — compose with the OSPREY agent, review, start and stop in the BLUESKY panel, and add plans of your own.

Bluesky Plans