Build Profile — profile.yml#
Every key a build profile’s profile.yml accepts, what the build does with
it, and what the deployment does with the result. For what a profile is and
how to write one — the concepts, the worked walkthrough, extends
composition, and troubleshooting — see Build Profiles.
Profile YAML reference#
Field |
Type |
Default |
Description |
|---|---|---|---|
|
string |
required |
Human-readable profile name. It is display text only; no container, volume or image is named from it. |
|
string |
required |
The deployment’s name on a host. It names the compose project, its
volumes ( |
|
string |
required |
Facility data tree, relative to the profile directory ( |
|
string |
|
The facility directory of a mounted machine repository, relative to the
profile directory (e.g. |
|
string |
|
A bundled preset name, or a path relative to this file, to inherit from. The parent is deep-merged under this file, recursively; a cycle is refused. A login file may not spell it, and an override that would give a materialized profile a parent is refused (see Build Profiles). |
|
string |
required |
LLM provider. Names an entry in |
|
string |
|
A model id the provider serves. Omitted: the provider entry’s
|
|
string |
|
Channel finder pipeline ( |
|
string |
from preset |
Control-system connector ( |
|
integer |
absent |
Shorthand for |
|
list |
|
Panels the web workspace offers beside the terminal. A framework
panel is named by its id; your own is a list entry plus its address
under |
|
string |
|
Panel id the web terminal opens on. Must be an entry in
|
|
mapping |
|
Named web-terminal layouts, as label to dock layout: a tile
|
|
string |
|
The bundled |
|
mapping |
|
Dot-notation settings for the generated |
|
mapping |
|
Entries to subtract from what this profile would otherwise bring (see Removing something a profile brings). |
|
list |
|
Built-in artifacts to install. Your own files go in the matching convention directory instead. |
|
mapping |
|
MCP server definitions to inject (see MCP server injection). |
|
mapping |
|
Container services the deployment runs (see Services). |
|
boolean |
|
|
|
mapping |
absent |
Where the project is built, pushed and run: |
|
mapping |
absent |
Declares a simulated machine the deployment runs — and, optionally, a second copy of it standing in for the live target (see The virtual_accelerator block). |
|
mapping |
absent |
Declares a stored archive for a simulated machine: a MongoDB store and a recorder the deploy stands up, seeds and records into (see The va_archiver block). |
|
mapping |
absent |
Deploys the event dispatcher and its workers (see The dispatch: block). |
|
mapping |
absent |
Deploys the Bluesky stack (see bluesky). |
|
mapping |
absent |
Deploys the |
|
mapping |
absent |
Deploys the optimizer service and its Redis job store (see optimizer). |
|
mapping |
absent |
Deploys the |
|
mapping |
absent |
Deploys one chat bridge, which hands messages to the event dispatcher,
so it needs a |
|
mapping |
|
Overrides merged into the rendered |
|
mapping |
embedded backend |
Where the deployment’s agent record is kept, how long, and who reads it.
Written into the rendered |
|
mapping |
|
The deployment’s watchdogs, by name; each one’s files live in
|
|
mapping |
|
The applications the deployment runs, by name; each one’s files live in
|
|
string |
|
Login files only: |
|
mapping |
|
Commands to run at build phases ( |
|
mapping |
|
Variables the deployment needs: |
|
list |
|
Python packages to install into the project venv. |
|
mapping |
|
Base interpreter the project environment is built from (see The execution environment). |
|
string |
|
PEP 440 specifier (e.g. |
|
string |
|
How to install OSPREY in the project venv: |
|
string |
|
Python used by MCP servers: |
|
mapping |
written |
Which preset this profile was materialized from, that preset’s hash, and
the hash of the |
Configuration overrides#
The config: section uses dot notation to set any key in the generated
config.yml. Nothing is inherited from underneath it: a profile
osprey init materialized carries every key its preset configures, each on
the line that documents it, so reading the block is reading the deployment’s
configuration. osprey config --defaults prints the wider ledger — every key
the framework reads and what it falls back to when no line spells it.
Warning
Always write overrides as dotted keys, one per line — never as nested
YAML. A nested block counts as one override whose value replaces the entire
subtree. config: {claude_code: {aliases: {opus: claude-opus-5}}} wipes out
everything else under claude_code (servers, permissions, …), silently.
The dotted form claude_code.aliases.opus: claude-opus-5 changes just that
setting.
# The channel-finder paradigm is a top-level field, not a `config:` key: the
# build renders `channel_finder.pipeline_mode` and the per-mode pipelines
# from it, and spelling either under `config:` is refused.
channel_finder_mode: middle_layer
config:
# Control system: which backend the deployment talks to. Required — see
# the posture floor below.
control_system.type: virtual_accelerator
# The tier key: how far a login's switch may go. `never`, `asked` or
# `allowed` (silence is `never`); each login still arms a machine from the chip.
control_system.writes: asked
# Limits checking. This pair is the deployment's, and every type
# inherits it: `exclusive` = only channels in the limits file can be
# written, `optional` = channels in the file are held to their limits and
# every other channel is written with no limits ...
control_system.limits_checking.enabled: true
control_system.limits_checking.mode: exclusive
# ... while a per-type block replaces it whole for one type, and does not
# fall back to the keys above. Both settings have to be stated: one alone
# is refused by `osprey build` and `osprey validate`.
control_system.connector.virtual_accelerator.limits_checking.enabled: true
control_system.connector.virtual_accelerator.limits_checking.mode: optional
# Archiver: where history is read from. Required alongside a control
# system.
archiver.type: mongodb_archiver
# Set your real facility zone: it governs how the agent reads operator
# times (parsed as facility-local) and renders every timestamp — not
# just a display label.
system.timezone: America/Los_Angeles
# Approval policy for the tools the write switch does not govern
approval.enabled: true
approval.default_policy: always
That is the shape osprey init --preset demo writes, with the
timezone changed and a per-type limits block added. Pointing the same deployment at a real machine
(control_system.type: epics) is a larger edit than the one line, because
the va_archiver: block the preset ships records a machine the deployment
would no longer be baselined on. osprey build refuses it rather than
rendering it. The tier key needs no change: it is target-blind
(Who May Write). See
Use the Virtual Accelerator.
Note
Connector types whose name contains a dot are the one place the flat form
does not work. A custom connector is named by its module path, and the build
splits only the first key of each config: entry on dots — so
control_system.connector.mypkg.SiteConnector.limits_checking.enabled
renders the type’s module path as two nested keys, mypkg and
SiteConnector, instead of the one key the connector is actually called.
osprey build and osprey validate refuse that entry by name rather
than letting it render somewhere nothing reads. Write such a type as its own
map key under a dotted prefix, which is the one spelling that puts the block
where the connector looks for it:
config:
control_system.connector:
mypkg.SiteConnector:
limits_checking:
enabled: true
mode: exclusive
That entry replaces the whole rendered connector section. connector
is the last key of the dotted prefix, and a leaf is assigned verbatim — so
the mapping has to carry every connector block the deployment needs, not only
the custom type’s. Copy the virtual_accelerator and epics
blocks, with their gateways, ports and probe channels, out of the
control_system.connector.* keys this profile already spells under
config:, or from a prior render’s config.yml.
Nothing outside connector is disturbed, and nothing refuses a mapping
that leaves a block out: the deployment simply comes up without the addresses
that block held.
What is never right is a bare control_system: mapping beside flat
control_system.* keys — the bare top-level key is the only spelling that
does not merge, since deeper dotted prefixes are walked into rather than
assigned over. It replaces the whole rendered section, so which of the two
reaches config.yml depends on key order. osprey build and osprey
validate refuse that pair by name too. Built-in types have no dots and take
the flat form.
Keys the build renders#
A few config keys are not yours to state. The build writes them from the
project layout, the port layout, providers.yml, or a top-level profile
field — so a config: line for one of them is a second home for one fact,
and the render would silently win. So osprey build and osprey validate
refuse that line by name and say what supplies the value instead:
config: channel_finder.pipeline_mode is rendered by the build; the top-level
`channel_finder_mode:` field sets it. Remove it from profile.yml.
Rendered key |
Set it here instead |
|---|---|
|
the top-level |
|
the top-level |
|
the top-level |
|
the top-level |
|
the top-level |
|
|
|
the top-level |
|
nothing — the build takes them from the repository it renders into |
|
the |
|
|
Each entry claims every key beneath it, in every spelling: a dotted key, a dotted prefix over a mapping, a fully nested block, or any mix reaches the same rendered leaf and is refused the same way.
web.panels.<id>.enabled is the one exception. It is derived from
web_panels: too, but a config: line that agrees with the selection is
accepted; only one that contradicts it is refused.
The provider catalog — providers.yml#
providers.yml sits beside profile.yml and lists every model provider
the deployment can name. osprey init writes it; osprey build renders the
whole file into api.providers in build/config.yml; the profile’s
top-level provider: field picks one entry by name.
providers:
my-gateway:
api_key: ${MY_GATEWAY_API_KEY}
base_url: https://my-gateway.example.org/v1
default_model: claude-sonnet-5
models:
- claude-opus-5
- claude-sonnet-5
- claude-haiku-4-5
base_url, default_model and models are required. api_key is
optional and is normally an ${ENV_VAR} reference resolved at run time from
the repository’s .env — keys are never written into this file. models
lists the ids the gateway serves, spelled as it spells them, and
default_model — one of them — answers when the profile names no model:.
api_protocol:
anthropic marks an Anthropic-native endpoint rather than an
OpenAI-compatible one. supports_images: true or false says whether
images reach the model on the provider’s OpenAI route. Absent, the provider’s
own declaration answers.
Three rules follow from the catalog being the one home for these facts:
A
config: api.providers.*key is refused, namingproviders.ymlas the place to declare the provider.provider:naming an entry the file does not declare is refused, and the message lists the names it does declare.The file is yours to edit, like
profile.yml:osprey validaterefuses and lists no difference from the catalog OSPREY ships.osprey init --revalidatekeeps every value in the file and adds the entries and keys OSPREY added since the repository last took the catalog. An entry or key you deleted is not added back.
The posture floor#
Five config keys have no safe unstated answer, so osprey build refuses a
deployment that leaves one of them silent rather than letting a reader’s
fallback decide. The refusal names the dotted key and profile.yml. The gate
reads the rendered config, so a key a preset’s config: block spelled, an
injector wrote, or a tier inherited counts as stated.
Key |
Required when |
|---|---|
|
the |
|
the |
|
the |
|
the |
|
always |
A render that switches the controls server off — every bundled shared login does — is asked for neither control-system key: it has no control system to state a type for.
Code review#
Key |
Default |
Value |
|---|---|---|
|
|
|
|
|
|
|
|
The reviewer’s prompt file; a relative path is anchored at the repository root |
|
|
The execution modes reviewed on a Python run |
|
|
Seconds one review may take |
The feature requires the code-review and memory-guard hooks in the profile’s hooks:
list. A change in the rendered config.yml applies on the next call, and only time_limit
needs osprey build and a session reload. Review the Agent’s Code sets
it up; Code review says what it does.
Preset updates#
A profile osprey init wrote records the preset it came from under
provenance:. From then on the profile is yours: no difference from the
preset is refused or listed, whether you changed a value, added a key or dropped
a list member. osprey init also keeps a plain copy of what the presets
produced, so OSPREY can tell a preset’s later changes from your edits. When a
preset bundled with your OSPREY has changed since the repository last took it,
osprey validate and osprey build print one line saying so, and
osprey init --revalidate applies the changes. It applies a change only
where you kept the preset’s old value, and leaves your own edits alone. The
same holds for each tier file, against the bundled tier it names, and for
providers.yml and triggers.yml. An application copied into apps/ is
code: when the preset’s copy changes, --revalidate says so once and copies
nothing.
A profile written before the config: block carried everything spells only
what its facility changed, and still names a packaged app template at its top
level. Such a profile is refused, naming that key and the verb that fixes it:
osprey init --revalidate # preset from provenance:
osprey init --revalidate --preset demo # or name it
Such a profile has no record of what its preset said when it was written, so
this once it writes every key the preset documents and the profile lacks into
the profile’s own config: block, each under the comment the preset
documents it with, drops that retired key, and refreshes providers.yml. It
only adds — nothing already in the file is touched — and your deployment’s own
selections are left for you and named in the output.
MCP server injection#
The top-level mcp_servers: key declares the MCP servers a build wires into
the agent. The build records each entry in the rendered config.yml (under
claude_code.servers) and renders it from there into .mcp.json (server
configuration) and .claude/settings.json (tool permissions) — so a later
osprey build re-renders them instead of losing them. For the procedure, see
Add an MCP Server.
The agent loads only the servers this build renders into .mcp.json: every
launch passes --strict-mcp-config with that file, so a Claude Code plugin’s
server or a claude.ai connector never starts, and declaring a server here is how
you give the agent one. A server whose name puts its tools under
mcp__plugin_ or mcp__claude_ai_ is refused at build, because those
namespaces are denied on every launch.
mcp_servers:
my_server:
command: "{current_python_env}"
args: ["-m", "my_server"]
env:
CONFIG: "{project_root}/build/config.yml"
API_KEY: "${MY_API_KEY}"
permissions:
allow: ["safe_tool"]
ask: ["write_tool"]
Remote servers declare a url instead of a command, plus an optional
transport — http (streamable-HTTP, the default) or sse (legacy
Server-Sent Events):
mcp_servers:
matlab:
transport: http
url: "http://localhost:8008/mcp"
permissions:
allow: ["mml_search"]
command and url are mutually exclusive, and stdio servers must not set
transport (launching via command is the transport). A port: may
stand in for a whole url: for an HTTP service the deployment publishes on
one port, port: 8008 derives http://localhost:8008/mcp. It is
mutually exclusive with command for the same reason url is, and it
cannot stand in for an sse server’s url: transport: sse always
requires an explicit url, whether or not a port is given, because an
event stream does not live at the derived /mcp path. The derived block the
build records alongside a port: names the container URL under the server’s
own key — so name the compose service after the mcp_servers: key or that
URL points at no host.
Placeholders: {project_root} resolves at build time to the absolute
project path, and {current_python_env} to the interpreter the framework’s
own MCP servers run under (the project venv under the default
python_env: project; see the key table above), which is what a Python
server shipped with the profile should launch under too. ${ENV_VAR} is
preserved for the container or shell to resolve at runtime.
Permission wiring: for a server named my_server with
allow: ["safe_tool"], the build adds mcp__my_server__safe_tool to the
allow list.
Each entry under mcp_servers: takes these keys:
Key |
Default |
Meaning |
|---|---|---|
|
|
The executable that launches a stdio server. Excludes |
|
|
Arguments passed to |
|
|
For a |
|
|
|
|
absent |
The address of a remote server. Excludes |
|
|
|
|
absent |
The one port an HTTP server publishes, an integer in 1–65535. With no
|
|
|
|
|
absent |
The server’s write tools, as bare names: no |
|
absent |
A render-context key that must be truthy for the server to render. A
server an application projects with |
|
absent |
The application the server is projected for, by name ( |
A key the entry does not define is ignored with a warning that names the release from which it is refused.
Shipping the server’s code#
Put the package in the profile’s mcp_servers/ directory — one directory per
server. The build copies it to build/_mcp_servers/ in the project, so the
launch command finds it:
my-facility/
mcp_servers/
my_server/
__init__.py
__main__.py
server.py
mcp_servers:
my_server:
command: "{current_python_env}"
args: ["-m", "my_server"]
env:
OSPREY_CONFIG: "{project_root}/build/config.yml"
PYTHONPATH: "{project_root}/build/_mcp_servers"
permissions:
allow: ["safe_tool"]
The directory name and the mcp_servers: key are independent: the directory
delivers the code, the key launches it.
Tool permissions#
By default OSPREY blocks a handful of general-purpose tools — Bash,
Edit, WebFetch, WebSearch, Monitor (background shell commands),
EnterWorktree (a new git worktree on disk), and every Claude Code plugin’s
and claude.ai connector’s MCP tools (mcp__plugin_*, mcp__claude_ai_*) —
so a stock control-operator agent cannot shell out or browse the web. These defaults
are overridable per facility from config:, using dotted keys:
config:
claude_code.permissions.remove_deny: ["WebSearch", "WebFetch"] # drop from the deny list
claude_code.permissions.allow: ["WebSearch"] # then allow outright
claude_code.permissions.ask: ["WebFetch"] # or route to human approval
Key |
Effect |
|---|---|
|
Remove entries from the deny list. Matches an entry exactly — the string has to be the one being denied, character for character. Removing a write-capable tool that nothing else gates fails the build — see below |
|
Add facility-specific deny entries |
|
Add allow entries (no approval prompt) |
|
Add entries that route through human approval |
|
Remove entries from the ask list |
Deny wins, and it wins at runtime too
Permissions resolve as deny > ask > allow, and a static deny entry
cannot be overridden during a session — an in-session “allow once” will not
unblock it. Use ask for tools you want gated but still reachable. For the
same reason, listing a tool under ask or allow does nothing until you
also remove it from the deny list.
You cannot un-gate a tool that can write
Bash, Edit, Write, NotebookEdit, Monitor and
EnterWorktree can write files or shell out, so osprey build refuses a profile in which one of them is neither
in permissions.deny nor matched by a PreToolUse hook matcher. A
remove_deny: ["Bash"] with nothing put in its place is therefore a build
failure, not a silent widening. (The shipped presets gate Write and
NotebookEdit with the memory-guard hook rather than denying them, so
ordinary memory and notebook writes still work.)
The build checks that a covering rule exists, not that the hook behind it
refuses anything: a PreToolUse hook that exits 0 without a
permissionDecision allows the call. A tool whose only cover is a matcher
your own profile declares therefore builds with a warning — check that hook
really denies. Matchers are read the way the agent runtime reads them: the
bare tool name, a | alternation, any regex that matches the name
(unanchored), or */.*/empty for every tool.
How the deny list is assembled#
The permissions.deny array in the rendered .claude/settings.json is
built from three sources, in this order:
Source |
How it is treated |
|---|---|
The framework’s deny defaults |
Minus anything the profile lists under |
The profile’s own |
Minus anything the profile lists under |
The write kill switch |
Appended last and never filtered |
The third source is the one to know about. A profile whose tier is
control_system.writes: never does not merely stop the write path at run
time; it also puts the framework servers’ write tools into the rendered deny list. Those entries are
generated, not authored, and no remove_deny reaches them. (Tools a profile
lists under control_system.write_tools are a different mechanism: they
never reach permissions.deny, in any render, and are refused by the
writes-check hook instead.) A never profile that also writes
remove_deny: ["mcp__controls__channel_write"] still renders that deny —
which is the point. A read-only posture that a later edit could quietly lift
would not be a posture at all.
An armed tier renders differently. The login’s switch decides each write
at run time, so nothing is denied up front. A write tool whose rule carries
both the writes-check hook and an approval hook leaves ask: with the switch
off, writes-check refuses it before any operator is offered an approval for a
write the switch forbids; at asked, the approval hook asks. A tool missing
either hook keeps its static ask. The boundary is carried per call by the
safety hook and by the connector behind it (Who May Write). The
static deny is the stronger of the two, so reach for a never tier whenever
the requirement is “this tier can never move anything”.
Permission lists grow across extends; taking an entry out is explicit
The permission lists under config: — deny, ask and their
remove_* companions — union with the ones they inherit. A child
profile or a tier can add to an inherited permission list; to
take an entry out it has to say so, with remove_deny / remove_ask
(which match by substring) or with exclude: config: naming the exact
entry (see Removing something a profile brings).
That is why a preset that wants to withhold a privilege from every tier and
grant it back to one writes the floor as deny, and lets the privileged
tier lift it with remove_deny. Writing the floor the other way round —
putting the tool under ask at the base and expecting a child to
remove_ask it — does the opposite of what it looks like: the base’s
remove_ask would union into every child, including the one meant to
keep the approval prompt, and strip that prompt away. deny is
subtractable per tier, which is the direction a floor has to work in.
The bundled demo preset is built exactly this way: its
base denies the agent’s own deployment-editing tool, and the admin
tier is the single delta that removes that deny. Writing the floor is
not only a convention. A web terminal served without a login by a tier
that can edit the deployment is refused by osprey validate, osprey
build and osprey up alike, wherever the deployment has a login page
at all — with auth.method at token (the default) or none there
is no wall to be exempt from, and the same exposure is reported as an
advisory instead. On a profile that
wrote no floor at all, where every tier holds everything, the only
remedy that refusal can offer is to write one. See
Privilege Tiers.
Services#
The services section defines facility containers the deployment runs
alongside OSPREY’s built-in ones.
services:
typesense:
template: services/typesense # relative to the profile directory
config:
port: 8108
api_key: "${TYPESENSE_API_KEY}"
The template directory must contain at least docker-compose.yml.j2. A
profile-relative template must resolve inside the repository (one outside is
refused, see A profile is self-contained), and its contents are folded into the
profile hash. It is copied into the project’s services/ tree, and the
service is registered in config.yml. Optional config values land under services.<name>.
A service directory placed in the profile’s services/ convention directory is
carried across the same way and marked as yours — that is what
osprey scaffold claim services/<name> produces.
One config key is read by the build itself: network, which is either
bridge (the default — the service joins the compose network and publishes
the ports it wants reachable) or host (it shares the host’s network
namespace, which is what a service needs to see broadcast traffic or reach
ports other software publishes on the machine). Your template has to render the
setting for it to mean anything, and osprey build refuses a service that
declares network: host whose render does not carry it. See
Network attachment: bridge or host for what host mode changes and for
dispatch.network, the single knob that covers the event dispatcher and its
workers.
A second config key the build reads is env: a list of host environment
variable NAMES the service passes through to its container, in the order you
write them.
services:
typesense:
template: services/typesense
config:
env: [TYPESENSE_TELEMETRY, HTTPS_PROXY]
Names only, never values — each becomes a NAME: ${NAME} the deploy env
chain fills in, so rotating a value is an edit to .env and a restart. A name
nothing sets arrives as an empty variable rather than an absent one.
The event dispatcher and its workers take the same axis as dispatch.env,
one list for both halves, because the build writes both of their service blocks
itself:
dispatch:
triggers: my_triggers.yml
env: [EPICS_CA_ADDR_LIST, EPICS_CA_NAME_SERVERS]
Writing env: on either half’s own service block is refused for the same
reason network: there is: the build would overwrite it.
A third config key the build reads is http, default false: it says the
service answers HTTP on the port it publishes, and the deploy summary prints
its address as a link instead of a bare host:port. Leave it out for a
service that speaks any other protocol.
A fourth pair of config keys says what a service on the host network binds.
listens defaults to true; listens: false says the service opens no
listening socket. bind_env defaults to none; it names the environment
variable the service’s compose template renders its bind address into. The two
may not be combined, and both are read only under network: host: osprey
up reads the bind address from the rendered compose file to decide whether the
deployment is reachable from other machines, and skips a service that listens on
nothing in its host-port check. OSPREY’s bundled services declare their own, so a
declaration on one is refused unless the service is claimed with osprey
scaffold claim services/<name>.
The dispatch: block#
dispatch: is a closed block: every key it accepts is listed below, and an
unrecognised one fails the build rather than being dropped into a default.
triggers is the only required key — writing the block at all is what opts
the deployment into the event dispatcher and its workers.
Key |
Default |
What it does |
|---|---|---|
|
(required) |
Bundled trigger-file name, or a path relative to the profile. A file beside the profile wins over a bundled one of the same name; editing it marks the build out of date, and a bundled file never does. |
|
|
How many dispatch workers the build deploys. |
|
|
|
|
|
Runs a worker executes at once. |
|
|
Queued runs held before the dispatcher starts refusing new ones. |
|
(from the port layout) |
Host port the dispatcher publishes. Unset resolves against the
deployment’s own |
|
(from the port layout) |
Host port worker 1 publishes, in host-network mode only. Bridge-mode workers publish nothing on the host. |
|
|
Host-port spacing between consecutive workers. Widen it to leave room for something else of yours between them. |
|
|
Wall-clock ceiling on one run, as |
|
|
How long a run may produce nothing before it is cut off, as
|
|
|
Agentic turns one dispatched run may take before the SDK stops it, as
|
|
|
Leading prefix trimmed off a channel address before the dashboard shows it, so a dense trigger list is not mostly the segment every address shares. It reaches the trigger sources that carry a channel; a source that renders an interval or a bare name has nothing to trim. |
|
|
Network attachment for the dispatcher and its workers together — see Network attachment: bridge or host. |
|
|
Host environment variable names passed through to both halves, in the order you write them. Names only, never values. |
|
(unset) |
The tier the dispatch workers run at: a file in |
Graph-mode channel finding#
channel_finder_mode: graph points the channel finder at the deployment’s
graph store: the agent searches the facility knowledge graph for channels
instead of reading a channel database. The store is the database, so the
profile ships no channel-database inputs. What it does need is a
services.graphdb block, and the paradigm works with either shape that block
comes in.
A deployment that runs its own store already has one.
osprey init --preset demo writes the services.graphdb.*
keys and the graphdb entry in deployed_services into the profile’s
config: block, and osprey up starts, bootstraps and seeds it — see
Container Deployment. That profile reads, in outline:
name: control-room
provider: anthropic
channel_finder_mode: graph
data: data
config:
services.graphdb.path: ./services/graphdb
services.graphdb.image: neo4j:5.26-community
# ... the JVM and query-bound keys the preset also ships
deployed_services: [postgresql, qmd, graphdb]
The mode reads the same services.graphdb block when the store is one the
facility already runs and this deployment only connects to. The keys that
express that are an explicit uri, username (default neo4j), and a
deployed_services list without graphdb in it. An edit replaces that list
whole, so write out the services you do want rather than the one you are
taking away:
channel_finder_mode: graph
config:
services.graphdb.uri: bolt://graph.facility.org:7687
services.graphdb.username: neo4j
deployed_services: [postgresql, qmd]
The procedure that goes with those keys — the password to place, what is minted
and seeded on each path, and how to load a corpus into a store OSPREY does not
run — is in
Pointing at a store the facility runs. A store
this deployment runs is seeded during osprey up; a store it only connects
to is not.
Removing the store means deleting those keys. A whole-block
config: services.graphdb: {} or a bare services.graphdb: with no value
is refused by name: an empty block reads as “a store at the defaults” wherever
the block is resolved, and a null one is what every resolver downstream trips
over. Neither removes anything, because nothing injects a store to subtract.
A profile that renders no services.graphdb block at all is refused at build time, naming
the missing block, rather than rendering a channel finder with nothing to read.
An attached project (deploy_services: false) is refused the same way unless
it names an external store, because it renders services: {} whatever its
own config: block says. For what the mode changes about the agent’s
answers, see How to Use the Channel Finder; for the corpus behind them,
Search the Facility Graph.
The qmd sidecar behind hybrid logbook search is guarded the same way. The
demo preset switches
ariel.search_modules.hybrid on and deploys the services.qmd sidecar that
answers it, but an attached project renders services: {} — so on its own it
would keep the mode with nothing behind it, and every logbook query would fail
with no qmd sidecar is configured. osprey build refuses that instead of
rendering it. A deploying profile is held to the same rule from the other side:
a client left switched on for a service the profile no longer deploys — the
bluesky MCP server after the bluesky: block was removed — is refused naming
the service missing from deployed_services, unless the profile names one
this deployment does not run (an external store’s uri, an ARIEL database
DSN).
An attached project rarely has to say anything, because the build tells it
where the host’s services are. Every client-facing fact — the sidecar’s port,
the graph store’s bolt port, the Postgres the logbook lives in, the Bluesky
bridge, the EVENTS and BLUESKY tab URLs — is copied
from the hosting deployment’s own render into each login built beside
it, so a service moved on the hosting profile moves every render with it, and
the bundled login files pin none of them. A login that spells one
of these keys with a different value is refused — the two copies would dial
different places, and the build names both. (A tier inherits the hosting
profile’s config: keys, so a port moved there is spelled in every tier as
the host’s own value, and agrees.) The rest of a deployed service’s block — its
image, its JVM sizing, the directory its compose fragment lives in — is dropped
from the render, with one exception: a key that names a file in the render’s
own data/ tree, such as the graph store’s ttl_path, stays, because the
render stages that tree too and its build derives the search index from it.
The same facts are checked again at run time: the reach category of
osprey health (and of the system-health tab, inside each user’s container)
resolves every live client’s endpoint the way the client does and knocks on it
(Configure Health Checks).
The virtual_accelerator block#
Declaring virtual_accelerator: gives the deployment a simulated machine: a
soft-IOC container that speaks EPICS over a real Channel Access port, brought up
by osprey up and served from the lattice the build renders (see
Use the Virtual Accelerator).
virtual_accelerator:
port: 5064
live_standin: true
Key |
Default |
Meaning |
|---|---|---|
|
|
Channel Access port the simulator serves on. The connector block the build writes follows this value, so changing it moves both. |
|
absent |
Deploy a second copy of the simulator as a third control target of
its own, |
|
|
pvAccess port the simulator publishes its model surface on. Like
|
Where the simulator runs#
This block deploys the simulator’s container. Where the deployment’s own
connector reaches the simulator is a pair of config: keys, not keys of this
block (see Two venues):
Key |
Default |
Meaning |
|---|---|---|
|
|
|
|
|
Milliseconds the simulator in process waits before it answers. Read in process only. |
The live stand-in#
live_standin deploys a second simulator container on its own Channel Access
port and gives the deployment a third control target, standin, dialled
through its own control_system.connector.live_standin block. Both containers
run one image over the same simulator view and the same active scenarios. The
two machines are told apart by a write to the sandbox not showing on the
stand-in and by the model RPC status naming its instance.
The stand-in is a machine of its own, not a rewrite of live. The build
never writes a key under control_system.connector.epics, so live means
the gateways the facility authored on a stand-in deployment exactly as on one
without: a facility already pointed at its own control system can stand a
rehearsal up beside it. What the stand-in rehearses is the procedure, not the
risk — control_target_set standin moves a session onto it, and
control_target_set live from there walks the real go-live path. See
Switch the Control Target at Run Time.
One fact, one home. The key is where the stand-in is described, and the build
derives exactly seven keys from it, all under
control_system.connector.live_standin:
the six
gateways.*keys —address,portanduse_name_serverfor each of theread_onlyandwrite_accessroles, pointing both lanes at loopback on the stand-in’s port over the Channel Access name server;probe_channel, copied from the simulator’s own, stated or derived from the facility file (see Settings the facility decides), since the stand-in is the same soft IOC over the same machine model. A deployment whose simulator has none gets none here either.
A profile that spells any of the seven in its own config: block is refused by
name at build time rather than silently having the derived copy win: two homes
for one fact are free to disagree, and an address left in config: reads as
the endpoint the standin target dials while every session on it is somewhere
else. The refusal is scoped to those leaves; the rest of the
control_system.connector.live_standin block is yours to write.
What the block does not decide. Write posture, limits checking and the operator acknowledgment are the profile’s, on a stand-in deployment exactly as on any other: they describe how the deployment is run, not where one of its targets lives. The limits pair is the deployment’s, and the stand-in inherits it:
config:
control_system.limits_checking.enabled: true
control_system.limits_checking.mode: optional
The build writes no limits_checking block under
control_system.connector.live_standin. See Limits Checking
for the two modes and the per-type block.
control_system.target_switch.live_gateway_acknowledged stays the live
machine’s alone — the stand-in’s equivalent is the live_standin line itself.
What the build refuses. Beside the duplicate-key refusal above:
a stand-in port that collides with
virtual_accelerator.port, with another port this profile spends, or with a hand-authored virtual-accelerator gateway port — the simulator and its stand-in are two endpoints, never one;control_system.type: live_standinon a profile that sets novirtual_accelerator.live_standin— a baseline naming a machine the deployment does not stand up;a
va_archiverblock beside a stand-in on a baseline that is neither simulated nor the stand-in, since the recorder would sample one machine into a store the deployment reads as another’s.
On a laptop the second container is a real cost — a second simulator runs beside the first — and deleting the line is the remedy; the how-to above says when that is worth it.
The va_archiver block#
A deployment that serves simulated channels still needs somewhere to keep what
those channels did. Declaring va_archiver: is what gives it one: the build
adds a MongoDB store and a recorder to the service stack, osprey up
seeds the store with history and then records the running machine into it, and
the mongodb_archiver connector reads it back.
va_archiver:
host: localhost
retention_days: 30
hot_span_hours: 48
hot_cadence_sec: 10
tail_cadence_sec: 60
Every key is optional and the defaults describe a working archive; the block’s presence is the decision, not its contents.
Key |
Default |
Meaning |
|---|---|---|
|
|
How far back the archive reaches — both what a fresh deployment holds and what a running one keeps. |
|
|
How much of the recent end is kept at the dense cadence. May not exceed
|
|
|
Seconds between samples inside the hot span. |
|
|
Seconds between samples outside it. Must be a whole multiple of
|
|
|
How often the recorder samples the live machine. |
|
|
How often one of those samples is additionally kept for the full retention span, so recorded history survives as the dense copy ages out. Same whole-multiple rule. |
|
|
How often the recorder re-reads the deployment’s config to decide whether
to record at all. It records only for a |
|
derived |
Canary channel for a derived |
|
|
Where the store is. Required when |
|
|
Host port the store publishes on — or, for an attached project, the port the other host published. |
|
|
Where the samples live inside the store. |
|
|
Block compressor for the collection: |
|
|
The database user the deployment creates and the agent connects as, and the database it authenticates against. |
|
|
Name of the variable holding that password. The value is minted into
the deployment’s |
|
|
How long the connector waits to reach the store. |
One fact, one home#
The block is where the archive is described, and the build writes the rest from
it. Do not also spell these in config: — a profile that does is refused,
by name, rather than silently having one copy win:
the connector’s eight connection keys —
archiver.mongodb_archiver.host,.port,.name,.collection,.auth.source,.auth.username,.auth.password_env,.timeout_s— all derived from the keys above;the shape knobs, written to
va_archiver.*in the renderedconfig.ymlfor the seeder and the recorder to read;health.categories.archiver, from the channel the build derives from the facility file or a statedfreshness_channel, an override checked against it.
Two homes for one fact are free to disagree, and the disagreement is the
dangerous case: a stale collection or host in config: points the
agent at an archive nothing is writing, which reads as empty rather than as
broken.
What the block does not do is select the archiver. Declaring where an archive
lives and choosing it as the deployment’s archiver are separate decisions, so
the block never flips archiver.type out from under you — set
config: {archiver.type: mongodb_archiver} yourself, or the project deploys a
store and then reads something else beside it.
Warning
osprey build refuses a profile that pairs a virtual_accelerator
control system served from its container with the mock archiver, or with no
archiver.type at all (which resolves to the mock): a simulated machine
whose history is synthesized at read time reports a past that never
happened, and nothing can catch it. The error names the fix — declare this
block and select mongodb_archiver, or point the archiver at a store you
run yourself. A project meant to be honestly storeless serves the simulator
in process instead
(control_system.connector.virtual_accelerator.serving: in_process), which
has no recorder and so may keep the mock archiver. See
Use the Virtual Accelerator.
Lifecycle commands#
Lifecycle commands run shell commands at three phases of the build:
pre_build — before the project venv exists (cwd: the repository root)
post_build — after the render, on the project venv (cwd: the built project)
validate — advisory checks that warn but don’t abort, on the project venv (cwd: the built project)
lifecycle:
pre_build:
- name: "Check dependencies"
run: "pip check"
post_build:
- name: "Build search index"
run: "python scripts/build_index.py"
cwd: "data"
timeout: 300
stream: true
Each step requires name and run. Optional: cwd (relative to the phase
default), timeout (seconds, default 120), and stream (print output live;
also available for all steps via --stream).
{project_root} is replaced with the built project’s absolute path.
In post_build and validate the project venv’s bin/ leads PATH, so
python and pytest resolve to the project’s own Python. pre_build runs
before that venv exists, and under --skip-deps no step gets one: those steps
see the shell’s PATH.
post_build and validate steps see the repository’s env chain, .env
over .env.shared, secrets in .env included; so do pre_build steps.
A step that writes JUnit XML to {project_root}/check_results.xml has its
tests printed as an Integration Test Results table when it finishes: each
test’s name, whether it passed, failed or was skipped, and its time. The file is
read from the project root whatever the step’s cwd, so name it with
{project_root} rather than relying on the working directory. The table
prints after the step that wrote the file and after no other: a step that writes
no such file, or leaves an earlier step’s file as it found it, prints no table.
The file stays in place, so a later step can read it. validate is the usual
phase for a test run, because its failures warn instead of stopping the build:
lifecycle:
validate:
- name: "Integration tests"
run: "pytest tests/integration --junitxml={project_root}/check_results.xml"
timeout: 600
Environment variables#
The env section declares what the deployment needs. required documents
variables the operator must supply; secrets live in the repository’s .env
and never in the profile (see Secrets).
env:
required:
- API_KEY
- DB_HOST
defaults:
LOG_LEVEL: info
Both lists are rendered into the repository’s .env.example, so an operator
opening that file sees them alongside every other variable. Required names must
match ^[A-Z_][A-Z0-9_]*$.
defaults values are additionally seeded into the repository’s .env by
osprey init, under their own section banner, so a deployment created from
the profile starts with them in force. Seeding is append-only: a value already
in the file — set by the operator, or minted by a deploy — always wins, and
later init runs never rewrite one. Declare a default only for a value the
profile’s author can honestly choose for every deployment (the
demo preset’s login passwords, say); values a site
should share across hosts belong in .env.shared, which is committed with
the repository and read by every host (see Environment Variables (the .env chain)).
Dependencies#
dependencies adds Python package specifiers to the built project. They are
installed into the project venv and recorded in its generated pyproject.toml:
dependencies:
- numpy>=1.24
- pandas
- scipy~=1.11
cd my-project
uv run osprey web # uses my-project/.venv
uv sync # rebuilds it from pyproject.toml
Builds run with --skip-deps create no environment and no pyproject.toml;
install dependencies yourself in that mode. The generated Dockerfile still
installs every declared requirement.
The execution environment#
dependencies says what else to install. The environment: block says
what the project environment is built on top of — which interpreter it starts
from, and, when that interpreter belongs to a virtual environment your facility
already maintains, which of its packages to carry over.
environment:
python: /opt/facility/analysis-env/bin/python # base interpreter
packages: # installed on top
- lmfit>=1.3
inherit_exclude: # left out of the freeze
- facility-inhouse-tools
All three keys are optional; the block as a whole can be omitted.
pythonThe base interpreter, as an absolute path. It may be a plain interpreter (
/usr/bin/python3.12) or the interpreter inside a virtual environment — the syntax is the same. The build aborts if the path does not exist or is not executable.packagesExtra requirements installed into the project environment. Resolved in the same install as
dependencies, so the two cannot disagree; where both name the same distribution, a pinned version wins over a bare name, and between two pinspackageswins.inherit_excludeDistribution names to leave out of the freeze described below. Only meaningful with a virtual environment base; declaring it otherwise is rejected at validation time rather than silently ignored.
Carrying a virtual environment’s packages over. Basing a project on a virtual
environment’s interpreter does not inherit its packages. What carries them
over is a freeze: when environment.python names a virtual environment’s
interpreter, the build records that environment’s installed distributions as
exact name==version requirements in the project’s pyproject.toml. The
project venv — and any container image built from it — installs that same set.
A pin in dependencies or packages overrides the version the base
happened to carry.
The freeze runs only when a base interpreter is declared. Without
environment.python the base is whatever interpreter OSPREY itself was
installed into — an accident, not a curated environment — and its packages are
deliberately not carried over.
The build stops if a package cannot be reproduced. Two cases are refused: a
distribution with no package-index coordinate (installed from a local path, a
VCS checkout, or a bare archive URL), and a version outside OSPREY’s own
requirement for that package. Every offending package is named in a single
message, along with the inherit_exclude block that clears all of them.
bluesky#
The bluesky: section configures the Bluesky stack a deployment brings up —
the bridge, the queue server, the BLUESKY panel and, optionally, the Tiled data
store. It accepts exactly twelve keys; a misspelled or unknown key fails the
build and prints the valid set:
Key |
What it does |
|---|---|
|
The bridge’s port. Defaults to its slot in the port layout, |
|
Deploy the Tiled data store alongside the stack. |
|
Tiled’s port. Defaults to the layout’s |
|
Run a second plan lane, so one deployment serves both its live machine and its virtual accelerator. |
|
A directory of your facility’s own plans — see Write Your Own Plans. |
|
Plans to remove from the catalog entirely, e.g. |
|
How many devices the bridge lists at once (default 500). A larger set is served a page at a time and can be narrowed by an exact name prefix. The same number decides when a refusal for an unknown device stops listing every device it does know and gives a count instead. |
|
How long a plan write waits for the readback to reach its demand before the move fails and the plan aborts (default 5.0 seconds). Raise it for devices that physically move; it never turns an unsettled move into a successful one. |
|
How close the readback must come to the demand to count as settled, as
an absolute difference (default |
|
How many runs’ live data the bridge keeps in memory, oldest dropped first (default 50). This is what decides how long a finished run stays readable in the web panel. |
|
How many rows of one run the bridge stores (default 10000). Rows past the cap are still counted, so a long run reports its true length over a truncated buffer. |
|
An externally-run RE Manager this deployment’s bridge fronts, as a
block of |
Whether a deployment can execute plans at all is not set here: it follows from the control system the deployment runs. See Plans and the Queue for what the stack looks like when it is up.
optimizer#
The optimizer: section deploys the optimizer service, which tunes machine
variables against an objective with Bayesian optimization (Xopt), and the Redis
store that keeps its jobs. The block’s presence is the switch. It accepts
exactly two keys; a misspelled or unknown key fails the build and prints
the valid set:
Key |
What it does |
|---|---|
|
The service’s port. Defaults to its slot in the port layout, |
|
A directory of optimizer environment files (YAML), mounted read-only into the service. Unset, only installed environment plugins are offered. |
Every write the optimizer makes goes through the control-system connector, so
the deployment’s write tier, channel limits and max_step apply to it, and
its put-log entries name it as osprey-optimizer. A run writes for the login
that started it: POST /jobs/{id}/start reads that login from the
X-Osprey-Owner header, and the run’s writes follow that login’s tier (the
staged login_tiers map). A run started with no owner has every write
refused. The routes that move hardware are guarded by
OPTIMIZER_LAUNCH_TOKEN, which osprey up mints into the project .env;
the token says a caller may start a run, not whose run it is. Drafts are not
guarded: creating one (POST /optimizations), editing it (PUT
/jobs/{id}/config) and selecting it (PUT /jobs/current) need no token. A
draft write reads the target’s setpoints and writes nothing to the machine.
GET /jobs/{id}/config returns the draft’s revision in its
X-Config-Revision header, and POST /jobs/{id}/start must name it
(?config_revision=): when the draft changed since it was shown, the start
answers 409 rather than run. The image is built locally on the first
osprey up; set OSPREY_OPTIMIZER_IMAGE to run a published one.
The agent reaches the service through the optimizer MCP server
(MCP Servers), switched on by
claude_code.servers.optimizer.enabled: true under config:.
A run writes only under one write authorization (Writing from a program), never under the owner’s switch alone, so the switch can stay off for the whole run and turning it on does not widen the run:
What it asks for. The setpoint channels the run writes, each with the run’s resolved window narrowed to the environment’s range and the channel limits database; a step per evaluation (
n_initial + n_iterations, each evaluation one write call) plus one for the completion write whenon_completeisapply_best(the default) orrestore, none forhold; an eight-hour expiry (OPTIMIZER_AUTHORIZATION_EXPIRES_S, held just under 24 hours) and a lease the run renews every 20 seconds. An evaluation whose objective is re-measured only reads it again: it writes once and spends one step.How it gets it. While the owner’s switch for the machine stands at allowed, the run writes its own. Otherwise it writes a request, its job’s
write_authorization.statereadsawaiting, and the owner approves it from the chip or withosprey write-authorization approve. A request that waits longer than 15 minutes (OPTIMIZER_AUTHORIZATION_WAIT_S) ends the runauthorization_timeout; a cancel while it waits withdraws it. A run that needs more than 100000 steps endsauthorization_too_many_stepsbefore it writes or asks for anything.How it ends. A run whose authorization is spent (
auth_exhausted), stopped (auth_revoked), expired, lapsed (auth_lease_lapsed) or written outside (auth_range,auth_channel) ends with that reason in its job’s error andwrite_authorization.reason, its results so far saved, and writes nothing more. Nothing asks again. A cancelled or failed run writes nothing either: restoring its starting setpoints is the operator’s call. A run that issued its own grant marks it revoked when it is done. One a person approved stands until its expiry, but once the run stops renewing its lease — it finished, failed or crashed — it no longer blocks an approval of another program on its channels, about two minutes later, when the approver can see the run’s ledger; with none in sight it blocks until it expires. A paused run still renews, so it still blocks.
The results restore (POST /results/{env}/{timestamp}/restore, after its
preview), PUT /environments/{name}/variables and POST
/environments/{name}/evaluate are each one write under a one-step
authorization of their own, for exactly the values they write and for the login
their X-Osprey-Owner header names. The service issues that grant itself,
writes once and revokes it, which the switch allows only while it stands at
allowed: below it the call answers 403 with the refusal’s reason and
writes nothing; set the switch to allowed from the chip and repeat the call.
There is no request to approve for a manual write; a run still asks for one.
What these rules do not cover:
Plugin environments are trusted code. An installed environment plugin runs inside the service; one that ignores the run’s execution mode, or writes through a client of its own instead of the control-system connector, is outside the write authorization, the switch and the put-log. Install only plugins you would trust with the machine.
The owner header is trusted.
X-Osprey-Owneris taken as given from any caller holding the launch token: a token holder can start runs, and make manual writes while that login’s switch is at allowed, as any login. While the switch is at allowed a run issues its own write authorization, so the person who clicks Start is the only reviewer of its plan.Drafts are open to any caller. Any caller that can reach the service can edit any draft or move the current-job pointer. The revision protects a start only if the token-holding panel or relay forwards the revision it displayed. For a plugin environment, preparing a draft constructs the plugin with the caller’s
environment_config.The single-job slot needs Redis. During a Redis outage longer than the slot’s lease (about a minute) while a worker is writing, the slot can lapse and a second job can start.
Windows the service cannot close. A cancel that lands between a run’s last cancellation checkpoint and its completion write does not stop that write; a shutdown that has to kill a worker can stop it in the middle of a write; a paused run keeps its lease renewing, so its authorization stays in force while it is paused; and
GET /environments/{name}/pvreads any channel the environment’s connector can reach.
With a writing tier the container binds the deployment’s write ledger,
var/write_ledger, read-write as OSPREY_WRITE_LEDGER_DIR: the run’s
requests, its ledgers and its own grants live there, and every web terminal
reads the requests from it. The service warns at start when it cannot write
there; every write is then refused auth_unreadable.
optimizer:
environments_dir: optimizer/environments