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, or uv sync --extra dev if working from a clone)

  • ANTHROPIC_API_KEY set 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)

logbook-search and logbook-deep-research query a seeded operations logbook for past events.

Archive + visualization

A store this project deploys serves historical data — seeded on the first deploy, then recorded from the running machine; the data-visualizer sub-agent turns it into interactive and publication-quality plots.

Operator skills

/diagnose, /session-report, demo-gallery, and demo-ui support common control-room workflows.

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_channels reads the search index that osprey build derives 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 up loads. It adapts an example from example_queries, can check the graph’s labels and properties with get_schema, then runs the query with read_cypher.

  • The rules. capabilities tells 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_state and alarm_config read 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 demo down to what your facility needs, or build up from hello-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 osprey commands.