Runtime Configuration — config.yml#
config.yml is the file an OSPREY deployment actually runs on. osprey
build renders it from the build profile, so the profile is where you edit a
setting and this file is where you look one up: Build Profile — profile.yml describes the
authoring side, and this page catalogues what the rendered result means.
The parts of that file gathered here are the models its simulator serves
(simulation:), the
diagnostic suite (health:), the browser UI’s documentation and feedback
settings (web:), the artifact gallery’s
extension types (artifact_server:), the Python sandbox’s run ceiling
(python_executor:), where screenshots are written (screen_capture:), the
links from an answer to a
logbook entry (ariel.entry_url_template), the login the agent’s SQL tool
uses on a logbook database you run yourself (ariel.database.readonly_uri),
how much of each logbook entry the agent reads (ariel.entry_text), whether
the agent shows its thinking (claude_code.thinking.display), the Phoebus
display bridge
(phoebus:), where PV records, alarms and put history come from
(pv_directory:), and the deployment keys that decide which container image each
service runs and how ${VAR} placeholders in the compose files are filled
in. Settings that only
ever arrive from the environment are in Environment Variables. A closing
note records the protected set — the files and keys no agent-side writer
may touch.
Each example names its file on its first line. # build/config.yml marks the
nested form that osprey build writes. Every build wipes and re-renders that
file, so set a key through the profile and never edit the rendered file.
# profile.yml, under config: marks
the dotted form you write in the profile’s config: block. Both spell the
same key: health.disk.min_free_gb: 2.0 under config: renders as
min_free_gb: 2.0 under disk: under health:. In a profile, always use
the dotted form; the reason is under “Configuration overrides” in
Build Profile — profile.yml.
simulation: — which models the simulator serves and how fast it ticks#
Key |
What it does |
|---|---|
|
The models the simulator serves, by name from the facility file’s
|
|
Seconds between the simulator’s ticks. Absent means |
|
The served simulator’s fast period: seconds between publications of
the readings a model serves faster than the tick, such as an
injection chain’s fast current. Absent means |
|
The scenarios a deployment that has never chosen a set starts in, by
name from the facility’s scenarios. |
texture is always served, and always last. A name the facility file does
not hold stops the build with a profile-invalid line that lists the valid
names.
A tier’s list applies when its simulator is served in process: each
process holds its own composite. On a tier whose baseline target is a
served va or standin the deployment’s container serves the deployment’s
list, so a tier that sets the key there stops the build with
profile-invalid.
# profile.yml, under config:
config:
simulation.models: [SR]
health: — the diagnostic suite#
osprey health always runs its built-in checks; a health: block adds a
facility’s own checks and tunes the suite’s timing. Everything in the block is
optional. For how to put these settings to work — the two recipes worth
starting from, cost classes, and the Health dashboard — see
Configure Health Checks; for the shape of
the --json report, see The osprey health --json Contract.
The health: block#
All configuration lives under a top-level health: key. Every field is
optional; an absent health: block runs the built-in checks with their
default timing.
# build/config.yml
health:
suite_timeout_s: 30 # poll-class wall-clock budget (default 30)
on_demand_timeout_s: 120 # on_demand wall-clock budget (default: sum of budgets)
interval_s: 300 # minimum server-side re-run interval
disk:
min_free_gb: 1.0 # disk_space warns below this many GB free (default 1.0)
max_used_percent: 90 # ...and at or above this % full (default 90)
plugins:
- my_facility.health # dotted module paths to plugin modules
categories:
beamline_services: # a facility-defined category of probe checks
checks:
- name: archiver
type: http
url: http://archiver.example.com/healthz
- name: bluesky_server
type: mcp
url: http://localhost:8931/mcp
providers: # metadata-only override of a built-in category
timeout_s: 15
Probe checks#
A declarative category is a named entry under health.categories with a
checks: list. Each check names a probe type and its parameters; the
suite runs the checks and grades each result ok / warning / error /
skip. Six probe types ship:
|
Purpose and parameters |
|---|---|
|
GET a URL and grade the response. |
|
Handshake an MCP server over streamable HTTP and list its tools. |
|
Check a deployed container’s state and healthcheck. |
|
Read one control-system channel through the suite’s connector and grade
the value. |
|
Make a minimal connectivity call to a model provider. |
|
Verify the deployment’s archiver is reachable and actually
accumulating data: query the newest archived sample of a canary
channel through the |
Note
For provider_canary, name: and provider: are distinct: name
is the check’s result identity (the row label in the report), while
provider selects which provider to test. When provider is
omitted, the probe falls back to name — so a check named after the
provider works, but to test one provider under a different row label you must
set both.
Every check also accepts the reserved keys name (required, unique within its
category), timeout_s, timeout_status, and requires: (below). Any
other key becomes a probe parameter.
Built-in service categories#
Beyond the always-on framework checks, these built-in categories are presence-gated: they contribute rows only when the corresponding service is configured or deployed, so a minimal build shows no empty tiles.
ariel— appears when a top-levelariel:block is configured. Reads the ARIEL interface’s open/healthpage, which needs no credential, and reports: reachability, logbook entry count, last ingestion time, and the registered search and enhancement modules. When the interface runs without its database, the reachability row is the only row. The interface sidecar runs withosprey web, so a CLI-only run on a stopped stack reports the interface as unreachable (awarning).channel_finder— appears when a top-levelchannel_finder:block is configured. Reports the active pipeline mode, verifies the pipeline’s channel-database file exists (a configured-but-missing database is anerror), shows the database’s age, and — for themiddle_layerpipeline — the channel count from the materialized DuckDB.The
graphpipeline reads different rows, because it answers from the graph store rather than from a file on disk. The pipeline row reports it as store-backed, and in place of the database rows the category reports the store’s reachability and its resource count — the same two readings thegraphdbcategory takes, so a stopped store warns rather than failing the suite. A graph-mode build configures nodatabase.pathand is never warned about one missing: there is no channel-database file in that paradigm to look for (see How to Use the Channel Finder). Thegraphdbtile is always alongside — graph mode needs that block — so these rows restate the same store readings in the channel finder’s own terms: whether channel search has anything to answer from.graphdb— appears when aservices.graphdbblock is configured (see Container Deployment). Two rows: connection, which dials the store over bolt and reports the round-trip latency, and resources, the number of(:Resource)nodes in the graph — the nodes the TTL corpus imports. Bootstrapping a store creates neosemantics bookkeeping nodes whether or not a corpus was ever loaded, so counting(:Resource)specifically is what keeps an empty graph from reading as a populated one; a count of zero warns and namesosprey build && osprey upas the remedy. The agent’s own graph tools report the same degraded states from the inside — see Search the Facility Graph.pv_directory— appears when apv_directory:section is configured. One row per configured service (directory, alarm logger, put log), read from that service’s probe on the current control target:okwith the service’s evidence while it answers,warningwith the reason when it cannot, andskipwhen it has no source on this target.pv_directory_alarm_feed(--full) starts the alarm feed, waits up to its deadline for catch-up and reports what the feed has read.reach— appears when this render has a client switched on for a shared service: hybrid logbook search and the OKF panel (the qmd sidecar), the graph MCP server (the graph store), the Logbook panel and ARIEL MCP server (Postgres), the Bluesky MCP server (the bridge), the EVENTS and BLUESKY tabs (their sidecars), and the virtual-accelerator connector. One row per service, and the address it knocks on is the one the client itself resolves from this config, in the process running the check — so the same category answers a different question on the host (whatospreycommands reach) and inside a per-user web-terminal container, where the health MCP server runs it (what that user’s agent reaches). A knock is a TCP connect; a closed port warns and names the config key the client resolved it from, and a client switched on with nothing to resolve warns with the key that would give it one — the same conditionosprey buildrefuses (Build Profiles).simulator— appears when the render carries a simulator view with a physics model and the deployment serves a simulator from a process of its own: thevatarget’s container, thestandintarget, or both. One row per target and model, read from the model’s status channel exactly asosprey sim status --targetreads it:okwhile the model serves,okwith “no deck, not built by design” for a model that names no deck and wires no channel, anderrornaming the error for a model that failed. A failed model serves NaN while the container keeps serving every other channel, so its healthcheck stays green and this row is where the failure shows. A target whose channels cannot be read is onewarningrow. A simulator served only in process gives no rows.
Note
The graphdb category dials bolt — services.graphdb.port_host, or
an explicit services.graphdb.uri — never the http_port_host the Neo4j
Browser and the container healthcheck use. That is the address its remedies
name, so a probe that fails is pointing at the port the seeder also uses.
Every row it produces is ok or warning, never error. A store that
is stopped, unreachable, rejecting its credential, or simply unseeded is a
service that is not running rather than a broken build, and the category says
so in one line instead of failing the suite.
All of them are ordinary categories: valid under --category, tunable via a
metadata-only override, and rendered as dashboard tiles with no extra
configuration.
Auto-derived MCP server checks (health.auto)#
Every MCP server your build wires up is already described in config.yml
under claude_code.servers. Rather than make you re-declare each one as an
mcp probe, the framework reads those blocks and builds an mcp_servers
category for you — one reachability check per server. It is on by default, so
you normally configure nothing.
# build/config.yml
health:
auto:
mcp:
enabled: true # default true — set false to drop the category
url_key: host_url # which URL to probe (see below; set by the build when web terminals are served)
A server is included when its claude_code.servers block carries a url and
a network block with a URL to reach it. Servers without those are skipped.
Which URL is probed. Each server block records two URLs: host_url (the
server seen from the machine, http://localhost:<port>/mcp) and docker_url
(the server seen from inside a container, http://<name>:<port>/mcp). The
category picks one automatically:
If you set
url_keyexplicitly, that choice is always used.A deployment that serves web terminals has the choice made for it. The terminals run on the host’s network, where a compose service name does not resolve, so
osprey buildwritesurl_key: host_urlinto each render, login renders included. That is the same address the agent dials. Setting the key to anything else in such a profile is refused at build time.Otherwise the framework detects whether the health check is itself running inside a container — the runtime’s own marker file,
/.dockerenvunder Docker or/run/.containerenvunder Podman, or anOSPREY_IN_CONTAINERenvironment variable you set yourself — and usesdocker_urlwhen containerized,host_urlon a plain host. Nothing in the shipped deployment sets that variable. This detection decides only for a render without web terminals; such a render setsurl_keywhen the detected answer is wrong for its network.
Expected tools. If a server block declares permissions (its allow
and ask tool lists), the derived check also confirms the server actually
exposes those tools, not just that it answers — a reachable server missing an
expected tool is graded an error. A server with no declared permissions gets
a plain reachability check.
Warning
docker_url assumes the container’s hostname matches the server’s key in
config.yml — a server named matlab is probed at http://matlab:….
If your compose service is named differently, the probe points at a host that
does not exist. Either rename the service to match the key, or set
url_key: host_url to probe the localhost URL instead. A deployment that
serves web terminals always probes host_url, so this caveat applies only
where docker_url is in use.
Timeouts#
timeout_s bounds a single check. Omit it and the probe’s per-type default
applies:
Check |
Default |
|---|---|
|
5 |
|
10 |
|
10 |
|
5 |
|
5 |
|
10 |
callable category (poll) |
|
callable category (on_demand) |
60 |
timeout_status sets the status emitted when a check’s own timeout fires —
error (the default) or warning. Use warning for a dependency whose
unresponsiveness should be treated as non-fatal:
# build/config.yml
health:
categories:
beamline_services:
checks:
- name: archiver
type: http
url: http://archiver.example.com/healthz
timeout_status: warning # a slow archiver warns, never errors
Warning
timeout_status: warning composes literally with requires: (below).
A requires: dependency passes when its status is ok or
warning — so a dependency that times out under timeout_status:
warning still counts as passed, and its dependents still run. Setting
timeout_status: warning on a check that gates others is therefore an
explicit opt-in to “an unresponsive dependency is non-fatal”; leave it at the
default error if a timed-out gate should skip everything downstream.
Dependencies (requires:)#
A check may declare requires: — a list of earlier checks in the same
category that must pass before it runs. A dependency passes when its status is
ok or warning; if any dependency does not pass, the dependent is emitted
as skip without running, and that skip in turn fails its dependents
(the cascade). Independent checks in a category still run concurrently — only a
genuine dependency chain serializes.
# build/config.yml
health:
categories:
beamline_services:
checks:
- name: gateway
type: http
url: http://gateway.example.com/healthz
- name: archiver
type: http
url: http://archiver.example.com/healthz
requires: [gateway] # skipped if the gateway check did not pass
A dependency must reference a check declared earlier in the list; a forward reference, a self-reference, an unknown name, or a duplicate check name is a configuration error at load time.
Category metadata overrides#
A health.categories.<name> entry with no checks: list is a
metadata-only override. It may set cost (poll / on_demand) and/or
timeout_s for a category defined elsewhere — a built-in (core) category or a
plugin category — without redefining it:
# build/config.yml
health:
categories:
providers:
timeout_s: 15 # give the built-in providers category a longer budget
model_chat:
cost: poll # run model_chat on every health check (use with care)
The reverse is rejected: a checks: list under a built-in category name is a
load-time error (“cannot redefine built-in category”) — use metadata-only keys
to adjust a built-in, and a new category name for your own probe checks.
Suite timing#
Three scalar settings tune the suite as a whole:
health.suite_timeout_s(default 30) — the wall-clock budget bounding all poll-class categories collectively. It is also the default budget for a poll-class callable category.health.on_demand_timeout_s— the wall-clock budget bounding all on_demand categories collectively (only relevant under--full). When omitted it defaults to the sum of the selected on_demand categories’ budgets.health.interval_s— the minimum interval between server-side re-runs. When omitted it derives asmax(60, 2 × suite_timeout_s); an explicit value must be greater thansuite_timeout_sor the config is rejected. This value is validated but not yet enforced byosprey healthitself.
At a cost-class deadline, unfinished checks are not dropped — every configured
check still produces a row (an eligible pending check becomes an error
“suite deadline exceeded”; a pending check whose dependency failed becomes a
skip), so the report always accounts for every declared check.
Disk-space thresholds#
Two keys set when the built-in file_system.disk_space row warns about the
filesystem holding the project:
health.disk.min_free_gb(default 1.0) — the row warns while free space is strictly below this many GB. GB is the unit the row prints: 1024³ bytes.health.disk.max_used_percent(default 90) — the row warns once usage is at or above this percentage. 100 warns only on a completely full filesystem.
Either key may be set alone; the other keeps its default. A value that is not a
positive number, a percentage above 100, or any other key under
health.disk is refused at load time: the configuration.health_config
row reports it as an error naming the key, and the disk_space row is a
skip rather than grading against numbers the operator did not choose.
The thresholds are not spelled as a file_system entry under
health.categories: that entry is a metadata-only override, which keeps only
cost and timeout_s.
web: — documentation, feedback, the bars and the chat pool#
The top-level web: section configures the browser UI the Web Terminal
renders — not the terminal process itself, which has its own web_terminal:
section. The keys below:
aim the sidebar’s two utility controls
bound the feedback store
name the deployment
decide who is offered the onboarding tour
choose whether the terminal is offered
size the operator-chat pool
bound how long a panel’s own server gets to start
set how often the file watchers re-read the tree
configure the CANOPY panel
Documentation and feedback keys#
Key |
Default |
What it does |
|---|---|---|
|
|
Where the Documentation control in the sidebar points. Set it to your own hosted copy of the docs. |
|
unset (no list) |
Issue trackers the feedback dialog offers, one channel each. A list of
|
|
|
|
|
unset (no Email channel) |
Recipient of the prefilled mail draft the dialog’s Email channel opens. Nothing ships here: the draft can carry a session’s scrollback, so name the mailbox your operators should reach before offering the channel. |
|
unset (no badge) |
Optional name badge in the terminal header, so otherwise-identical
deployments are told apart. The |
|
|
Ceiling in seconds on a single chat turn. |
|
|
How long an operator’s chat session may sit idle before it is reaped. |
|
|
Cap on concurrent operator-chat sessions. |
|
|
Seconds the terminal waits for a panel that runs its own server (the JUPYTER and CANOPY tabs) to answer before it greys that tab. The terminal starts serving once the panel answers or the wait passes, so a larger value also lengthens a start in which the panel fails. A value that is not a positive number is refused with a warning, and 60 applies. |
# build/config.yml
web:
docs_url: https://docs.example-facility.org/osprey
feedback:
trackers:
- kind: gitlab
url: https://git.example-facility.org/controls/osprey
label: Facility GitLab
- kind: github
repo: als-apg/osprey
label: OSPREY upstream
github_repo: ""
email: controls-support@example.org
docs_url, trackers, github_repo and email are unset in every
shipped preset — each is documented there as a commented example, so nothing
writes the project’s own address into your profile.yml. All four are read
straight from config.yml when present and fall back to the defaults above
when not.
Issue trackers#
The dialog renders one channel per tracker, between Local and Email,
in the order listed — trackers first, then the github_repo shorthand.
Every tracker channel works the same way the GitHub channel always has: the
report is recorded on the deployment, and the browser opens the tracker’s
new-issue form prefilled with it (or with a one-line pointer to the clipboard
when session context is attached). Nothing is posted on the sender’s behalf.
kind: githubneedsrepo(owner/name); the form ishttps://github.com/<repo>/issues/new.kind: gitlabneedsurl, the project’s base URL; the form is<url>/-/issues/new. The shape is the same on gitlab.com and on a self-hosted instance.
An entry that fits neither — an unknown kind, a GitHub entry with no
owner/name, a GitLab entry whose url is not http(s):// — is
reported in the log and skipped; the rest of the list stands. Two entries
naming the same target collapse to the first, so listing the upstream
repository under your own label does not render it twice beside the shorthand.
With no trackers and no github_repo written, the one tracker on offer
is the shipped default, so a bare deployment still reaches the OSPREY
maintainers. A facility that wants only its own tracker lists it and blanks
github_repo, as in the example above.
Blank, absent, and written-with-no-value#
Three ways of writing one of the three string keys (docs_url,
github_repo, email) mean three different things:
Leave the key out and the deployment uses the shipped default above.
Set it to an explicitly blank value (
docs_url: "") and the deployment declares it has no such target: the Documentation link is not rendered at all, or the matching feedback channel is refused with an explanation rather than aimed at the upstream maintainers. This is the air-gapped posture — blankingweb.docs_urlis how you avoid shipping a link that opens a dead tab, and blankingweb.feedback.github_reporetires the GitHub channel instead of aiming reports at the upstream maintainers’ tracker.Write the key with no value at all (
docs_url:and nothing after it) and it reads as absent, not blank — “I have not decided yet” rather than “there is none” — so you get the default. Write""when you mean none.
trackers has no blank posture of its own: an empty list, or none, simply adds no channel.
The feedback dialog’s Local channel is always available and needs no
configuration at all.
A build profile overrides any of these keys from its config: block in the
dotted form, e.g. web.feedback.email: controls-support@example.org.
The onboarding tour invite#
A first-time visitor to the terminal is offered a short guided tour of the
screen. web.tour decides who is offered it, and how often:
Value |
What the visitor sees |
|---|---|
|
The default. The invite card appears until this browser dismisses it — “Don’t show this again”, or finishing the tour — and then stops. |
|
The invite appears on every load and offers no permanent dismissal. This is the shared-screen posture: a wall display nobody owns should still greet the next person who walks up to it. |
|
No invite. The tour stays reachable from the sidebar’s ☰ More menu and the command palette. |
An unrecognised value is reported in the log and treated as once: a typo
costs you the setting, never the terminal’s startup.
On a multi-user deployment the policy can differ per user. A roster entry’s
tour: field — beside its theme: — is rendered into that user’s
container as OSPREY_WEB_TOUR, and the environment variable outranks
web.tour for that container, exactly as OSPREY_WEB_THEME outranks
web.theme.
The control-target picker#
# build/config.yml
web:
control_target_picker: true
The control-target block in the sidebar names the machine this terminal stands on
and opens the popover that switches it. The default is true. Set it to
false only for a terminal that reaches no machine: no control-system tool
server and no JUPYTER panel. The bundled shared logins logbook,
knowledge and channel-finder do.
The setting changes what the page shows, not what the agent may do. With it
off, the sidebar has no control-target block. A value that is not a boolean is
reported in the log and true is used.
Offering the terminal#
web.terminal: false removes Open terminal from the Agent pane’s session
switcher on every login the render serves, and /ws/terminal closes with code
4403 before any process starts. The default is true. A value that is
not a boolean is reported in the log and true is used; a config file that
cannot be read closes it. osprey build refuses a profile that still states
expert_view, the key this one replaced.
How often the file watchers re-read the tree#
The file panel and the artifact gallery both learn about a change from the
operating system’s own change notifications. Those notifications can go quiet —
the watch is live, and the system simply stops delivering to it for a while —
and for as long as that lasts, neither surface hears about anything and neither
one knows it. web.file_watch_reconcile_interval_s is the second trigger:
on that interval, each watcher re-reads the directories it is tracking and
announces whatever the notifications did not. It is therefore the ceiling on how
long a change can stay invisible.
# build/config.yml
web:
file_watch_reconcile_interval_s: 2.0
The default is 2.0. What the number costs is one directory listing per
tracked directory per interval — and a directory is tracked once something in it
has changed, never the whole workspace up front. A directory the notifications
never announced is picked up one level per interval from the nearest tracked
ancestor, so a deep tree costs one further listing per interval while it is
being discovered and nothing once it is. A deployment whose workspace is very
large or very busy can raise the interval, trading a longer worst-case delay for
fewer listings. Lowering it does the opposite. A value that is not a
positive number is reported in the log and the default is used; there is no
value that switches the pass off, because a watcher with only one trigger is a
watcher that can go blind without saying so.
web.panels.canopy — the CANOPY panel#
The CANOPY tab is a built-in panel that each web terminal serves from two
processes of its own, one CANOPY per user (CANOPY).
Besides the enabled switch every built-in panel has, its block carries the
settings the terminal hands to those processes. The terminal reads them each
time it starts the panel’s processes, so an edit takes effect at the next
restart of a terminal.
Key |
Default |
Purpose |
|---|---|---|
|
the panel’s registry default |
Whether the tab is shown and its processes are started. A panel that is
absent from |
|
|
The view Trace opens with when its URL carries none, as the query
string Trace parses ( |
|
|
The view the correlation page opens with when its URL carries none
( |
|
|
The view the waveform page opens with when its URL carries none
( |
|
|
The screen CANOPY opens first, by its id in the deployment’s library:
its path under |
|
|
Ceiling in bytes on the live-value buffers one user’s CANOPY keeps in memory (256 MiB). A value that is not an integer keeps the default. |
|
unset |
A colour theme for the panel. A relative path is read from the project root; an absolute path is used as written. Unset keeps CANOPY’s own theme. |
There is no key for the confirmation dialog: it follows the chip’s write
switch, so a write click asks first at asked and not at allowed.
There is no url, label or health_endpoint either, because the
terminal starts the server itself, and no key that turns the agent’s screen
tools on or off, because those follow the panel.
The panel’s other properties are fixed in OSPREY’s panel registry
(osprey.profiles.sidecar_panels), not set in configuration: which of its
agent tools run without a prompt and which ask on every call (see
CANOPY), the two library checks an image build runs,
and the 34 s a stopping terminal gives a write already sent.
dangerously_allow_bash — waiving the Bash/launch-token refusal#
osprey up refuses to deploy a tier that is entitled to a Bluesky launch
token while its .claude/settings.json does not deny both Bash and
Monitor (which runs shell commands too): a shell could
read the token out of its own environment and arm a queue with no approval.
One root-level key waives that refusal, for a development box with a single
trusted operator and no live machine behind it:
# build/config.yml
dangerously_allow_bash: true
It takes the boolean true and nothing else — any other value is a config
error. Absent, the refusal stands exactly as before. It never waives the
refusal of a tier that holds an application’s launch token or a write agent
route beside an open shell. When set, every
osprey up prints a warning naming the tiers it waved through, and the
closing card carries a dangerously_allow_bash row. The key belongs to
the protected set, so the running agent cannot
set it. A build profile sets it from its config: block.
modules.web_terminals — the landing page and the render catalog#
The roster itself — users, default_tier, shared and
authorization.roles — is described in Multi-User Support.
Two more keys shape what the deployment serves.
landing.groups lays out the landing page as sections, in the order listed.
Each entry has a type and an optional label:
users— one card per person on the roster.names: hiddenreplaces the name cards with one sign-in button; it needsauth.methodpasswordoroidc, and only ausersentry takes it.shared— one card per login inshared, titled by the login’sname:, opened by anyone on the roster (Share a card with more than one person). The retiredappsreads assharedfor one release, with a lint warning.links— your own cards, each alabeland aurl.
# build/config.yml
modules:
web_terminals:
landing:
groups:
- type: users
label: Users
- type: shared
label: Shared logins
- type: links
label: Facility
links:
- {label: Elog, url: https://elog.example.org}
Left out, the page shows [{type: users}, {type: shared}]. A section with no
cards shows no heading.
modules.web_terminals.renders is the render catalog: one entry per file in
tiers/, keyed by that file’s name, with its kind (tier, or
shared for a login only shared: names), project and
project_path. osprey build writes it into build/config.yml; a
profile that spells it is refused. Set a render’s extra_mounts,
seed_base or image at the top of its login file instead.
artifact_server: — the workspace gallery’s extension types#
The gallery and the sidebar group artifacts by base form: plots,
trends, tables, documents, dashboards, images, data
(runs is the script-run group, not declarable).
artifact_server.extension_types adds your own kinds, one dotted line per
type:
# profile.yml, under config:
config:
artifact_server.extension_types.beam_study: {label: Beam study, base_form: plots}
artifact_server.extension_types.rf_scan:
{label: RF scan, base_form: tables, viewer: viewers/rf_scan.mjs}
Each type takes a label (what the sidebar and gallery show), a
base_form it conforms to, and an optional viewer: a .js or
.mjs path relative to the project root (see
A facility artifact kind and its viewer). An installed package declares types under the
osprey.artifact_types entry-point group, its viewer inside the package.
osprey build refuses an unknown base form, a key or label that collides
with a base form or another type, and a missing or out-of-tree viewer; at
runtime a bad type is logged and skipped, and a bad viewer is dropped. Types
are read when the artifact server and the MCP workspace server start, so a new
one arrives with osprey build and a restart.
The old categories block under artifact_server: is retired:
osprey build refuses it and says to declare
artifact_server.extension_types instead.
Two other keys sit in this block. artifact_server.max_timeseries_file_mb
(default 200) is the largest timeseries data file the gallery will draw as a
chart or lay out as a table. Over it, those two views refuse with a 413 and
say so; the file itself stays downloadable either way. The handler reads the
whole file into memory to build the view, so raising the number spends that
much memory on the machine serving the gallery — which is why it is a facility’s
to set rather than a fixed bound: how big an export gets is a property of your
archiver, and how much memory the gallery host has is a property of your site.
artifact_server.page_size (default 20) is how many artifacts the gallery
asks for at a time. It fetches the next page as the list is scrolled, so a
store with thousands of entries opens as fast as one with twenty. The same
number bounds any other reader of the listing; a request may name its own size
up to 200, and a configured value above 200 is capped there.
python_executor: — how long one agent script may run, and what it inherits#
python_executor.execution_timeout_seconds is the wall-clock ceiling on a
single agent Python run. It defaults to 600 — ten minutes — and a run that
reaches it is killed and reported as a timeout, which the response
deliberately classes as the sandbox’s decision rather than as a failure of the
submitted script:
# profile.yml, under config:
config:
python_executor.execution_timeout_seconds: 1800
Raise it for a facility whose legitimate analyses run long — a fit over a
day of archived data, a scan reconstruction — and lower it where a runaway
script holding the sandbox is the worse outcome. The value is read once in
the sandbox’s MCP server process and held for that process’s lifetime, so a
change lands after osprey build and a restart of the stack. The value
must be a finite, positive number of seconds; any other value, null
included, refuses every run, so no run is left without a time bound.
Agent Python — the python executor, the visualization tools and plan
validation — and the notebook server with its kernels start with a fixed set
of environment variables from the host:
paths, locale, the interpreter, TLS trust, proxies, plotting caches, the
control-system client settings (EPICS_*, TANGO_*, ENSHOST) and the osprey names the run itself reads. Nothing else from the
host reaches it. python_executor.child_env_passthrough adds names to that
set, for an analysis library that reads its own variable:
# profile.yml, under config:
config:
python_executor.child_env_passthrough: [HDF5_PLUGIN_PATH, OMP_NUM_THREADS]
The list takes exact names only. It cannot add a credential osprey itself holds (the web-terminal, panel and dispatch tokens, a bridge launch token): naming one is an error, and the run does not start.
ariel.entry_url_template — links from an answer to the logbook entry#
ariel.entry_url_template is your logbook’s own address for one entry, with
a single {entry_id} placeholder. It is unset by default; the presets that
ship an ariel: block carry it as a commented line.
# profile.yml, under config:
config:
ariel.entry_url_template: "https://logbook.example.org/entry/{entry_id}"
When the key is set, every entry the ARIEL tools return carries an
entry_url: the search and browse results, entry_get,
entries_by_ids, the rows of sql_query that select entry_id, and the
result of entry_publish. The id is URL-encoded before it is filled in. The
agent is told to link that URL as given and never to build one, so with the key
unset it shows plain entry IDs. An entry that exists only in ARIEL gets no URL,
because the logbook has no page for it. Every write records which kind an entry
is in metadata.sync_status, and the URL reads that alone: local_only for
an entry entry_create wrote directly, a Logbook web save, a simulation seed,
an entry of a Generic JSON file or a publish the logbook did not take; pending_sync or synced for an
entry the facility logbook holds. Entries stored before the field was recorded
everywhere are stamped once by the ariel_only_sync_status migration. A
sql_query row also gets none when looking up the metadata it does not
select fails.
A template that does not format (a misspelled placeholder, an unbalanced brace)
is logged once as a warning and emits no URL; it never fails the read. The
ARIEL server reads the key from the loaded configuration, so a change lands
after osprey build and a restart of the stack.
ariel.database.readonly_uri — the SQL tool’s login on your own database#
The agent’s sql_query tool connects to the logbook database as a
SELECT-only login, never as the owner ingestion writes with. When OSPREY runs
the database, it creates that login itself. When you name your own database
with the uri key, name the read-only login beside it:
config:
ariel.database.uri: postgresql://ariel:${ARIEL_DB_PASSWORD}@logbook-db.example.org:5432/ariel
ariel.database.readonly_uri: postgresql://ariel_ro:${ARIEL_DB_READONLY_PASSWORD}@logbook-db.example.org:5432/ariel
Set, the key is used verbatim on any store; a derived store needs it only to
replace the <username>_ro login OSPREY creates. Without it the SQL tool is
not offered on a database named with the uri key: it is left out of the agent’s tools and guidance, and a call that
arrives anyway is refused with a message naming this key. Every other ARIEL
tool keeps working.
The login must be SELECT-only. The role is the boundary: OSPREY cannot check its grants on a database it did not provision. A value equal to the ingestion login is refused when the configuration loads.
ariel.entry_text: — how much of each entry the agent reads#
ariel.entry_text.listing_chars (default 500) sets how many characters of
each entry’s text keyword_search, semantic_search, hybrid_search
and browse return. ariel.entry_text.read_chars (default 1000) sets the
same for entries_by_ids. entry_get is never cut.
# profile.yml, under config:
config:
ariel.entry_text.listing_chars: 800
ariel.entry_text.read_chars: 4000
A cut entry keeps the start of its text in raw_text and adds
raw_text_truncated: true and raw_text_length, the full length. An entry
that fits carries neither field. The agent is told to call entry_get for
the rest.
Each value must be a positive whole number, and read_chars may not be below
listing_chars. Anything else is refused when the configuration is parsed:
the ARIEL MCP server does not start, and the Logbook panel reports the key. The
keys are read at startup, so a change lands after osprey build and a
restart. When choosing a value, the question is whether the part of an entry
the agent needs routinely runs past 500 characters.
claude_code.thinking.display — whether the agent shows its thinking#
claude_code.thinking.display sets whether Claude Code shows a summary of
its thinking. summarized, the default, shows the summaries, and they are
recorded with the session, where the operator chat and the agent timeline
display them. omitted leaves thinking out. Any other value stops
osprey build with a message naming the key.
# profile.yml, under config:
config:
claude_code.thinking.display: omitted
The key reaches a launch by one of three routes:
Project settings:
osprey buildwritesshowThinkingSummariesinto the project’s.claude/settings.json. This route covers interactive sessions only: the web terminals andosprey chatwithout--print.SDK runs: headless agent runs, such as the dispatch worker’s, pass
--thinking-displayto the CLI.osprey chat --print: the command line carries--thinking-display.
The two flag routes need Claude Code 2.1.228 or later. A launch through an
older build, or one whose version cannot be read, starts without the flag,
records no thinking, and logs one warning. The warning names the fix: pin the
agent CLI to 2.1.228 or later under config: in profile.yml and run
osprey build.
# profile.yml, under config:
config:
claude_code.cli_version: "2.1.228"
The key changes only how thinking is shown. Whether the model thinks, and how much, is unchanged.
phoebus: — the Phoebus display bridge#
These keys configure the phoebus MCP server, which is off until
claude_code.servers.phoebus.enabled is true; setting it up is covered in
Connect the Agent to Phoebus Displays.
Key |
What it does |
|---|---|
|
Host of the Phoebus agent bridge. Default |
|
Port of the agent bridge. Default |
|
Panel name to |
|
|
|
What the agent may do through the Phoebus bridge. |
|
The archiver bound into generated Data Browser plots. Unset, plots show live values only. |
|
Where Data Browser |
|
Where PNG snapshots are written. Default |
PHOEBUS_BRIDGE_URL, PHOEBUS_REQUIRE_HANDLE and PHOEBUS_ARCHIVER_URL
outrank their keys; see Environment Variables.
pv_directory: — PV records, alarms and put history#
This section feeds the Channels panel’s All PVs view and the pv-directory
MCP server. Each source answers on the control targets it serves: type
and the three sub-blocks on live and standin, the simulator and
alarm_state.replay_file on va.
Key |
What it does |
|---|---|
|
The facility’s directory service; |
|
The service URL. The build refuses a |
|
Seconds one call may take. Default |
|
The login a proxy in front of the service asks for: |
|
The directory property shown as a PV’s description. Default
|
|
Properties a search matches as whole values. Default
|
|
The properties a PV page shows. Unset, every property the record carries. |
|
Properties never shown. |
|
The largest result set fetched whole for facets, the origin filter and
CSV export. Default |
|
The record-name suffix of each IOC health role ( |
|
The directory property naming an IOC’s engineer. Default |
|
Alarm history: |
|
Current alarm state. |
|
The alarm feed on |
|
Put history: |
pv_directory.caveats and each sub-block’s caveats are lines shown with
every answer from that source. A sub-block takes the same settings keys as
the directory. The Kafka client is the alarm-state extra
(osprey-framework[alarm-state]); without it the build warns and the feed
is unavailable. A container gets it by setting OSPREY_PIP_SPEC to that
requirement (The Project Image).
Simulator-only form. A section without type lists the simulator’s channels
and IOC health PVs on va. A build with no simulator has nothing to list:
it warns, and every section answers “not available for this target”.
Off. osprey set config.pv_directory=null, or pv_directory: null in
a profile that extends a preset with the section, removes it. That spelling
builds only over a parent that writes the section as one nested mapping,
never as dotted pv_directory.* keys. The shared logins
tiers/logbook.yml and tiers/knowledge.yml switch the pv-directory
server off
(claude_code.servers.pv-directory.enabled: false).
A facility with ChannelFinder, the Phoebus alarm services and caPutLog:
# build/config.yml
pv_directory:
type: channelfinder
settings:
url: https://channelfinder.example.org/ChannelFinder
display:
# Shown first on a PV page.
detail_properties: [recordDesc, iocName, hostName]
ioc_health_suffixes: {heartbeat: HEARTBEAT, uptime: UPTIME}
alarm_log:
type: phoebus_alarm_logger
settings:
url: https://alarmlogger.example.org
alarm_state:
type: phoebus_alarm_server
settings:
bootstrap_servers: kafka.example.org:9092 # osprey:not-a-port — Kafka's broker port
topic: Accelerator
# The feed the simulator target replays.
replay_file: demo:example-alarms
put_log:
type: caputlog
settings:
url: https://caputlog.example.org
caveats: [Logs puts made through the CA gateway only.]
screen_capture: — where screenshots are written#
The workspace server’s screenshot_capture tool saves every capture as a
PNG file and records the file’s path in the artifact gallery.
screen_capture.output_dir names the directory those files go to:
# profile.yml, under config:
config:
screen_capture.output_dir: /srv/operator-captures
Unset, it is screenshots under the agent-data root (agent_data.base_dir,
var/agent_data by default), which is correct for most deployments and is
why no preset ships the key. A relative path is anchored on the project root,
the directory holding profile.yml, never on the working directory of the
process that started the server; ~ expands to the home directory. The
directory is created on the first capture. The key is read once per MCP
server process, so a change lands after osprey build and a restart.
Deployment — service images and ${VAR} interpolation#
Two deployment-wide surfaces are settled in config.yml rather than in a
compose template: which image each service runs, and how the ${VAR}
placeholders in the rendered compose files are filled in. Declaring a service
in the first place, and the env chain those placeholders resolve against, are
covered in Container Deployment and
Environment Variables (the .env chain).
Overriding Service Images#
Every service image resolves through the same three-layer chain — an
environment variable wins, then a config.yml key, then the packaged
default. One row per image:
Service |
Environment variable |
Config key |
Packaged default |
|---|---|---|---|
postgresql |
|
|
upstream pin |
mongodb |
|
|
upstream pin |
graphdb |
|
|
upstream pin |
event_dispatcher |
|
|
|
dispatch_worker |
|
|
|
nextcloud_bridge |
|
|
|
gchat_bridge |
|
|
|
teams_bridge |
|
|
|
slack_bridge |
|
|
|
ariel_sync |
|
|
|
archive |
|
|
|
history |
|
|
|
bluesky |
|
|
|
bluesky (Tiled sidecar) |
|
|
upstream pin |
bluesky (Redis sidecar) |
|
|
upstream pin |
bluesky_web |
|
|
|
optimizer |
|
|
|
optimizer (Redis sidecar) |
|
|
upstream pin |
optimizer_web |
|
|
|
virtual_accelerator |
|
|
|
qmd |
|
|
|
Point either of the first two layers at an internal registry mirror or a pinned digest when your deployment host cannot (or should not) pull public images.
The agent record’s ClickHouse store is an upstream pin with no row and no
environment variable: the profile’s agent_record.clickhouse.image is the
only way to change it.
Which of these images a deploy builds, and what naming another image does to that, is in When a deploy builds an image.
A row whose packaged default reads upstream pin is an upstream pin — an image somebody else publishes, named exactly as they publish it. Every other row is built by OSPREY from your project, and its default reference is assembled rather than fixed: a project name, a per-service suffix, and the two axes below.
dispatch_worker, ariel_sync, archive and history share one
row value on purpose: all four run the bare project image, so all four read
OSPREY_WORKER_IMAGE. Set that variable and all four services move to the
image you name. history (the history page) is rendered whenever the
deployment’s web terminals sign people in (auth.method of password or
oidc); it is never listed in deployed_services. Browsers reach it on
the history page’s origin, a second server of the web tier on its own port:
modules.web_terminals.history_port (deployment.port_base + 2 by
default), or modules.web_terminals.history_origin, the address stated
verbatim beside modules.web_terminals.external_origin when a load balancer
is what browsers reach. The two must share a host.
The two image axes#
An OSPREY-built default is always spelled the same way:
<registry>/<project><service suffix>:<tag>
Two stack-wide settings supply the ends of that name, so an entire deployment can be moved to a registry — or to a different tag — without touching any of the rows above:
Axis |
Environment variable |
Config key |
When neither is set |
|---|---|---|---|
Registry |
|
|
no prefix at all |
Tag |
|
|
|
Platform |
none: set in |
|
built for this host |
# build/config.yml — every OSPREY-built image comes from the mirror,
# at the tag the pipeline pushed
images:
registry: registry.example.org/accelerator
tag: "2026.08.1"
# or, for one build
OSPREY_IMAGE_REGISTRY=registry.example.org/accelerator \
OSPREY_IMAGE_TAG=2026.08.1 osprey build
For each axis the environment variable wins, then the config key, then the
packaged default. A blank value counts as unset on both layers — an
exported-but-empty variable is how a shell spells “I did not set this”, so a
stray OSPREY_IMAGE_TAG= cannot render an image reference with no tag. A
trailing slash on the registry is optional: one is added if you leave it out,
and never doubled if you put it in.
Two things about when and where this applies are worth having straight:
The axes are the innermost layer, not an override. They decide what the packaged default of an OSPREY-built image is. A
services.<name>.imagepin still beats them for that one service, and anOSPREY_<SVC>_IMAGEvariable still beats both. Setting an axis moves everything you have not pinned individually.The axes are read when the compose files are rendered, not when the containers start. Export them for the
osprey buildthat produces the deployment; the per-imageOSPREY_<SVC>_IMAGEvariables, by contrast, are filled in by compose atosprey uptime. With neither axis set the render is what it always was —<project>:localand its siblings — so a deployment that never heard of them is unaffected.
The axes never touch an upstream pin. Prefixing mongo:7 with your
registry would name an image that exists in no registry.
images.base_registry moves the Docker Hub ones onto a mirror; a services.<name>.image pin moves one.
Where ${VAR} values come from#
Compose fills in ${VAR} placeholders in the rendered compose files from two
sources: the env file(s) the command passes, and the environment of the shell
you typed the command in. The two supported providers disagree about which of
those wins, and the disagreement is a straight inversion:
Provider |
What gets substituted when both sources set a variable |
|---|---|
Docker Compose v2 |
The exported shell value. |
podman-compose |
The env-file value. It resolves from the env file before the calling shell, so the export reaches nothing. |
You do not have to remember this. osprey up compares the two sources on
every start, and when an exported variable disagrees with the value the env
chain resolves to it warns by name — never by value — and states which value
the provider it just probed will actually use, plus what to do about it. The
reliable habit is to put the value in the env chain and leave your shell out of
it: that is the one gesture that means the same thing on both providers.
The protected set#
A closed list of files and config keys may not be rewritten by the running
agent, whichever surface the write arrives through: the rendered
config.yml, .claude/settings.json, .mcp.json, CLAUDE.md, the
safety hooks, rules and skills, the limits and plan-device tables — and, inside
config.yml,
the key families that gate writes and approval (control_system.*,
approval.*, hooks.*, claude_code.*, among others). These artifacts
are owned by the build profile: edit them in the profile and run
osprey build. Every refused attempt names the owning channel and is
recorded in the audit trail, under
an audit entry filed under the acting identity, whose surface names
the surface that refused it.
See also
- Build Profile — profile.yml
The build profile these settings are rendered from.
- Environment Variables
Settings that arrive from the environment rather than from
config.yml.- Configure Health Checks
Putting the
health:block to work, and the Health dashboard.- Run the Web Terminal
Running the terminal the
web:settings render.