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, run and operate the agent, extend it for your facility, then explore the bundled services and tutorials.
Build & Deploy a Project#
Build a facility-specific assistant from a profile you own — convention directories, taking ownership of framework artifacts, personas, and secrets.
The end-to-end walkthrough: one deployment repo from osprey init
through the CI scaffolding to a running three-service stack.
Set up and switch between supported LLM providers — Anthropic, OpenAI, Google,
CBORG, AMSC i2, Ollama, and others — via config.yml.
Drive the Osprey agent with open-weight or self-hosted models via the
translation proxy, and benchmark their capability with scripts/benchmark/.
Create, configure, and deploy an OSPREY project from osprey build through
osprey up to a running instance.
Build and run the container image generated for every project — build args, path relocation, air-gapped mode, and Kubernetes notes.
Run & Operate the Agent#
The browser cockpit for the Osprey agent — launching it, theming every OSPREY interface at once, and adding your own themed side panels.
Serve a whole team from one host — a landing page plus a private containerized Web Terminal per user, in read-only and write-capable capability tiers.
Run the Osprey agent in your native terminal with companion services accessible in a browser.
Run the OSPREY agent headlessly from CI pipelines and automated workflows
with osprey query — read-only, structured JSON output, and clear exit codes.
Turn external events — webhooks and cron ticks — into headless Osprey agent runs, deployed as containers or run locally.
Let your team ask the Osprey agent questions from Nextcloud Talk or Google Chat and get answers, plots, and files back in the same conversation.
Emit the agent’s logs and metrics over OTLP to any backend, or deploy the opt-in local OpenObserve store alongside your project.
Extend osprey health with facility probe checks and plugins, and tune
the suite’s cost classes and timeouts via the health: config block.
Extend & Integrate#
Create a custom connector to integrate a new control system protocol (beyond EPICS and Mock) with OSPREY’s protocol-agnostic architecture.
Build and register a new FastMCP server to expose domain-specific tools that the Osprey agent can discover and call.
Run agent-generated Python scripts safely in a containerized environment with access to the OSPREY runtime API.
What the Open Knowledge Format is and why OSPREY stores facility knowledge as cross-linked markdown, plus how to structure, author, and serve a bundle to the agent on demand.
Bundled Services & Tutorials#
Search, filter, and explore control system channels using the Channel Finder service and its web interface.
Search over facility electronic logbooks with keyword and semantic retrieval modes, plus multi-step reasoning delegated to the Osprey agent.
Run the Control Assistant tutorial against a containerized PyAT soft-IOC that serves real EPICS Channel Access with live storage-ring physics.
Run measurement scans through a durable queue — compose with the Osprey agent, review, start and stop in the BLUESKY panel, and add scan plans of your own.
See also
CLI Reference — complete reference for all
osprey commands: build, deploy, config, health, claude, web, and more.