The Demo Deployment#
The Hello World Tutorial built a single-server agent that reads channels by their exact PV name. A production control room needs more: operators think in terms of devices and physics — “the booster’s defocusing quadrupole” — not PV strings; they need to search the electronic logbook, pull historical trends, and produce shift reports. This tutorial builds the demo deployment, which adds those capabilities on top of the same simulator, now served from its container, and the same safety model.
By the end you’ll have an agent that finds channels from natural-language descriptions, searches a seeded operations logbook, plots archived data, and runs control-room operator skills.
Prerequisites
Required:
Python 3.11+
Claude Code CLI installed
Osprey framework installed (
uv tool install osprey-framework, oruv sync --extra devif working from a clone)ANTHROPIC_API_KEYset in your environment
Recommended:
Finish the Hello World Tutorial first. This tutorial assumes you already understand the simulator in process, the safety limits system, and the human-approval flow, and it does not re-teach them.
Note
New to Osprey? Start with the Hello World Tutorial.
It covers project layout, the controls MCP server, and the safety model
in detail — everything on this page builds directly on it.
Step 1: Build the Project and Bring It Up#
Create a project from the demo preset:
osprey init osprey-demo --preset demo
cd osprey-demo
osprey build
As in Hello World, this writes one repository whose profile.yml is the
source and whose build/ is the render; provider keys go in the repository’s
.env.
No hardware is involved, so every example below is safe to run; hardware writes are still gated behind the human-approval prompt.
Unlike hello-world, the preset ships a full facility description under
data/facility/ (places, devices, channels, groups, models and limits), from
which osprey build writes the facility graph and every other file a
service reads (Describe your facility), a seeded electronic
logbook, and an archive of its own — a real store this project deploys,
seeds and records into — plus a set of sub-agents and operator skills.
Note
First run may take 1–2 minutes to create a virtual environment and install dependencies. Subsequent builds are near-instant.
Then bring the stack up (this needs Docker or Podman):
osprey up
This starts the containers the preset declares: the Virtual Accelerator the agent reads and writes — a containerized simulator with LUME-backed physics, laid out in Virtual Accelerator — and the archive, a MongoDB store and a recorder service that holds what those channels did.
The simulator serves two physics models: SR, solved as a periodic machine,
and LINE, a short synthetic transfer line solved single-pass, whose
channels start with LINE:.
The first deploy seeds the archive, and it is the step that takes the longest. It writes about a month of history for every channel the machine serves, reporting a step under the start phase every 15 seconds or so while it works. The duration at the end of each step is how long that slice took:
→ Starting osprey-demo
· seeding the archive base: 2,908 channels over 30 days (minutes on a first deploy)
· seeding archive: 8,960 documents written across 2,908 channels (17.4s)
· seeding archive: 17,920 documents written across 2,908 channels (15.0s)
...
· archive base: seeded 57,600 documents x 2,908 channels (2026-07-12 09:14 to 2026-08-11 09:14 UTC) in 96.3s (14.2s)
The counts and durations above are an example from an earlier run. Yours depend on how many channels your facility serves and on the retention settings.
Each of those documents holds one instant across every channel, which is why the count is in the tens of thousands rather than the millions. Expect a minute or two on a first deploy — it is writing, not hanging. Later deploys check what is already stored against the settings now in force and skip the seed when it already matches.
Note
The store is compressed (zstd) and bounded by its retention window: at the shipped settings it stays under 2 GiB on disk, and samples expire rather than accumulating forever. Tuning that is Step 7.
Step 2: What’s Different from Hello World#
The demo preset keeps the same controls MCP server and the
same safety hooks, then adds production capabilities. The most visible additions:
Capability |
What it adds |
|---|---|
Channel finder (sub-agent) |
Resolve channels from a natural-language description by searching the facility knowledge graph — no need to know PV names. |
Logbook search (sub-agents) |
|
Archive + visualization |
A store this project deploys serves historical data — seeded on the first
deploy, then recorded from the running machine; the |
Operator skills |
|
Web terminal |
A browser split-pane UI with logbook and channel-finder panels (documented separately — see Run the Web Terminal). The Channels panel’s All PVs view lists every PV the simulator serves (All PVs: the Control System’s Directory). |
The safety model is unchanged: limits checking, the pre-write check, and the human-approval prompt all behave exactly as in the Hello World Tutorial. Refer back to that tutorial’s “Write with the Guards Watching” step for the write-approval walkthrough — we won’t repeat it here.
Start the agent from anywhere inside the project — this tutorial stays in the
terminal with osprey chat; the web terminal from Hello World
(osprey web) works just as well:
osprey chat
Note
On first run, the OSPREY agent will ask you to trust the MCP servers in this project. Accept to allow the agent to use the control system and channel-finder tools.
Step 3: Find Channels by Description#
This is the headline capability. Until now you had to know the exact PV, as in Hello World:
You: Read channel SR:DIAG:DCCT:01:CURRENT:RB
With the demo, you describe the channel in plain language and the agent figures out the PV for you:
You: Read the current in the booster's defocusing quadrupole
The main agent delegates to the channel-finder sub-agent, which searches the
facility knowledge graph and resolves your description to a real PV before reading it.
The exact wording depends on your CLAUDE.md and output style, but you’ll see
something like:
Resolved "booster defocusing quadrupole current" → BR:MAG:QD:01:CURRENT:RB
Channel: BR:MAG:QD:01:CURRENT:RB
Value: 142.7 A
Status: OK
Try a few more descriptions — none of them require you to know the PV naming scheme:
You: What's the storage-ring beam current?
You: Show me the horizontal corrector magnet setpoints in the storage ring
The first resolves to SR:DIAG:DCCT:01:CURRENT:RB (the storage-ring DC current
transformer); the second resolves to the SR:MAG:HCM:*:CURRENT:SP family.
How it works. The preset runs the graph channel finder. It answers
from the facility knowledge graph that osprey build writes from the
facility file. The channel-finder agent works with twelve tools:
Keyword lookup.
search_channelsreads the search index thatosprey buildderives from the graph. It matches your words against each channel’s address, description, device, signals and class names, and returns the matches a page at a time with counts that help narrow the search.Graph queries. For questions about structure, such as what a device carries or how classes relate, the agent queries the graph store that
osprey uploads. It adapts an example fromexample_queries, can check the graph’s labels and properties withget_schema, then runs the query withread_cypher.The rules.
capabilitiestells the agent how addresses are spelled and which tool fits which question.All PVs. When the graph has no answer,
directory_search,directory_properties,pv_record,ioc_record,active_alarms,alarm_stateandalarm_configread the simulator’s own directory and its replayed alarms.
The agent never fabricates PV names: every address it returns is one the graph or the directory holds. For the other search strategies, see How to Use the Channel Finder.
Step 4: Search the Electronic Logbook#
The demo bundle seeds an electronic logbook with realistic
operations entries — RF trips, vacuum maintenance, beam-recovery shifts,
radiation surveys, and more. A fresh deployment starts in the rf-thermal
and demo-history scenarios, so the logbook and the archived history also
carry their incidents, such as an RF cavity that tripped on a thermal excursion
four days ago, and the sidebar lists three past agent sessions. Ask the agent about
past events in natural language:
You: Search the logbook for RF cavity temperature trips
The agent delegates to the logbook-search sub-agent, which matches the query against the logbook and summarizes what it finds:
Found 3 related entries:
- "Beam dump — RF CAVITY01 reflected power trip (thermal excursion)"
- "Investigation: Recurring CAVITY01 thermal excursions"
- "RF CAVITY01 cooling manifold repair"
Summary: CAVITY01 tripped on reflected power after its temperature climbed;
a follow-up investigation traced it to reduced cooling-water flow, later fixed
by a manifold repair.
For questions that span several entries and need synthesis (for example, “trace the root cause of the recurring CAVITY01 trips and what finally resolved them”), the agent can use the logbook-deep-research sub-agent, which performs a multi-hop search and stitches the entries into a single narrative.
Step 5: Pull Historical Data and Plot It#
The archive Step 1 seeded is what answers history questions here — the agent reads stored samples, not numbers made up when you ask. Ask for a trend:
You: Plot the storage-ring beam current over the last 24 hours
The agent finds the channel (SR:DIAG:DCCT:01:CURRENT:RB), reads its history
from the archiver, and delegates to the data-visualizer sub-agent to render
the result. The visualizer produces a self-contained figure artifact:
Read 8640 samples for SR:DIAG:DCCT:01:CURRENT:RB (last 24h).
Created interactive plot: beam_current_24h.html (artifact)
The data-visualizer can produce interactive Plotly figures, publication-quality
matplotlib images, dashboards, and LaTeX reports. Here the query hits the store
this project deploys; in production the same query hits your facility’s archiver
(see Step 7).
Two things follow from the history being stored rather than made up on demand. The last 24 hours come back at one sample every 10 seconds, because that is the cadence the archive holds recent history at — so a 24-hour trend is around 8,600 points, not a smooth line drawn to fit your window. And a question reaching back further than the archive does gets no points rather than a plausible-looking answer: ask for last year and the honest reply is that the archive starts about a month ago.
Step 6: Run Operator Skills#
The preset installs control-room skills you invoke directly. A few worth trying:
Generate a shift report — summarize the session’s actions into a polished, self-contained HTML report:
You: /session-report
The skill asks what kind of report you want (chronological log, technical analysis, or executive briefing), gathers the session’s artifacts, and saves an HTML report to the artifact gallery.
Triage an infrastructure failure — when a tool call or server misbehaves:
You: /diagnose
/diagnose investigates Osprey infrastructure problems (failed tool calls,
connection errors, configuration drift) and produces a structured root-cause
report — it is for diagnosing the assistant, not the accelerator.
Other skills: demo-gallery generates a showcase of plot and report
artifacts to explore the gallery’s capabilities, and demo-ui runs a short
scripted demonstration of the agent driving the web workspace — switching
panel tabs, focusing artifacts, composing layouts.
Note
Editing this deployment’s own configuration is deliberately not one of the
skills here. The preset withholds the setup-mode skill and the agent’s
setup_patch tool from the control-room agent — including the one this
tutorial runs — because rewriting the project is administration rather than
control-room work. The multi-user stack grants both to a single admin
login; see the tier table. To change something in
this tutorial, edit profile.yml and run osprey build, which is what
the rest of this page does.
Note
This project also ships a browser-based web terminal with logbook
and channel-finder panels. It has its own guide —
see Run the Web Terminal to launch it with osprey web.
Step 7: Tune the Assistant and Go to Production#
Choose a channel-finder strategy. The preset defaults to graph mode,
which answers from the facility knowledge graph this deployment runs. For a small
facility (under ~1,000 channels) the in_context strategy can be simpler and
faster. The strategy is a build-time choice, so set it and rebuild:
osprey set channel_finder_mode=in_context
osprey build
osprey set writes the value into profile.yml, so it stays in effect for
every later build — you can also just edit that file instead.
See How to Use the Channel Finder for a comparison of the strategies.
Tune how much history the archive keeps. Two settings decide the store’s
size and reach: retention_days (how far back it goes — 30 by default) and
hot_span_hours (how much of that is kept at the dense 10-second cadence —
48 by default; everything older is kept at 60 seconds). Both live in the
profile, in its va_archiver: block, which is the one place the archive is
described:
# profile.yml
va_archiver:
retention_days: 7 # a week is plenty for a demo, and seeds faster
hot_span_hours: 24
Rebuild and deploy after editing. The deploy notices the stored history no
longer matches what the profile asks for, says what changed, and reseeds it
(pass --keep-archiver-base to leave the old data alone instead). Do not
copy these keys into the project’s config.yml — the build writes that file
from the block, and a second copy is free to disagree with the first.
Size the host for the seed. At the defaults (about 4,700 channels over 30
days) MongoDB reached 7.4 GB of memory while seeding, and a Docker VM with
less OOM-kills it and the seed fails. Give the container engine that much
memory, or lower retention_days.
Switch to real hardware. As in Hello World, moving to production is a
configuration change, not a code change. Point the connectors at your facility
in profile.yml — EPICS here, as the example:
osprey set connector=epics
osprey set config.archiver.type=epics_archiver
osprey set va_archiver=null
connector names your control system — epics, doocs or tango —
and config.archiver.type the archiver that records it;
Use Connectors lists every one and the keys
each needs.
The archive this tutorial deploys is a simulated machine’s history, which is
not what you want against hardware — so the agent’s archiver switches to the
one your facility runs at the same time as the control system, and the recorded
store is dropped. All three lines are needed. The build refuses a facility
baseline that still carries a va_archiver: block, because that store would
be served as the real machine’s past. It does not check the archiver line:
without it the agent stays pointed at the MongoDB store you just dropped.
Because these are build-time inputs, re-render the agent’s artifacts and relaunch:
osprey build
osprey chat
Your queries don’t change — “Read the current in the booster’s defocusing quadrupole” and “Plot the storage-ring beam current over the last 24 hours” now run against your control system and its archiver. The connectors handle the difference; the agent, the channel finder, and your prompts stay the same.
Next Steps#
You’ve built the full demo: channel finding, logbook search, historical plotting, and operator skills. Where to go next:
Run your first plan: this project can run real measurement plans — ask the agent for a grid scan, review it in the BLUESKY panel, and start it from the BLUESKY panel, all against the Virtual Accelerator. Run Your First Plan walks through it in ten minutes.
Channel finder in depth: How to Use the Channel Finder compares the graph, hierarchical, in-context, and middle-layer strategies and explains each one’s data format.
Web terminal: Run the Web Terminal launches the browser UI and its panels with
osprey web.Start your own deployment: trim
demodown to what your facility needs, or build up fromhello-world; Build Profiles shows how either becomes a profile you own and edit.Architecture deep dive: the How OSPREY works and the Architecture section explain the agent + MCP design, the connector system, and the safety mechanisms.
CLI reference: see CLI Reference for all
ospreycommands.