Build Profiles#
A build profile is the directory your facility owns: one profile.yml, your
data tree, your secrets, and any rules, skills or scripts you write. osprey build
reads that directory and renders a project from it.
The profile is the source of truth. The project is a derived artifact — regenerable, and safe to delete and rebuild at any time.
What You’ll Learn
Creating a deployment repository and rendering its
build/zoneWhat lives in a profile: the convention directories,
data/, secrets, loginsMoving an artifact you want to own out of
build/and into the profileShipping and wiring your own hook scripts
Keeping a profile and its build in step
Prerequisites: A working OSPREY installation (uv sync).
Time: 15–30 minutes for a basic profile.
Preset → Profile → Build#
Preset — a bundled starting point, shipped inside OSPREY (
src/osprey/profiles/presets/). Runosprey profile presetsto list the presets that ship.Profile — the
profile.ymlat the root of your deployment repository, with the material it names beside it. Created once from a preset, then edited and kept in version control. Everything the preset configured is written out here explicitly: nothing is inherited at build time.Build — the
build/zoneosprey buildrenders. Never edit it in place; the next build wipes and re-renders the whole thing.
Because nothing is inherited, a later OSPREY release that improves a preset does not change your profile. To see what moved, create a fresh deployment in a scratch directory and diff it:
osprey init /tmp/fresh --preset demo
diff -u /tmp/fresh/profile.yml my-facility/profile.yml
Creating a deployment#
One command creates a deployment repository from a preset:
osprey init my-facility --preset demo
That writes the repository and stops. Look at the profile, edit it, then render and start it from inside:
cd my-facility
osprey validate
osprey build
osprey up -d
Every build reads the repository’s own profile
There is no build that renders straight out of a bundled preset. The preset
is applied once, at osprey init, and written out in full — after that,
profile.yml is the only input. A later OSPREY release that changes the
preset does not reach an existing deployment.
What osprey init writes#
my-facility/
profile.yml the full configuration — edit freely
providers.yml the catalog of model providers profile.yml selects from
data/ the facility tree (data/facility/) and the agent's other data
.env.example every variable the agent reads, documented, no values
.env.shared shared, committed defaults — no secrets
.env your values and secrets (when your shell had keys to seed, or the profile declares env.defaults)
.env.lock keeps two writers from editing .env at once; leave it be
README.md explains the layout, for whoever opens the repository next
triggers.yml the events the agent runs on (dispatch profiles only)
tiers/ one file per web-terminal login (multi-user presets only)
apps/ one directory per application the profile lists, with a
.provenance sidecar (only when it lists one)
web-terminal-context/ the shared base.md baseline, plus one seeded
directory per operator on the roster
rules/ rules/facility.md, the facility description, to rewrite in
your own words
watchdogs/ one directory per watchdog the profile declares
mcp_servers/ the MCP server packages the preset ships
.osprey/ what the presets produced, so --revalidate can tell their
changes from yours; commit it, never edit it
ci-extra.yml the facility's own CI jobs; never regenerated
.gitignore keeps build/, var/, the .env files and apps/*/panel/vendor/
out of version control
build/ rendered by `osprey build`; disposable
var/ agent memory and audit log; durable
triggers.yml, tiers/, web-terminal-context/, rules/,
watchdogs/ and mcp_servers/ appear only when the preset calls for them. A
demo deployment has all of them except mcp_servers/; a
hello-world deployment has only mcp_servers/.
No bundled preset lists an application, so apps/ appears only when you add
one (Build Your Own OSPREY Apps). A preset’s applications come with osprey init, never
through extends:: a profile runs the applications it lists and holds.
git init and an initial commit run at the end. There is no CI pipeline yet:
the profile ships its deploy: block commented out, so there are no
coordinates to render one from. Fill the block in and osprey scaffold ci
writes the pipeline — see Deploy a Facility.
The other directories for your own artifacts (skills/, agents/, and the
rest) are not created up front. Create the ones you need; a directory you
never create means the profile contributes nothing of that kind.
The facility tree#
data/facility/ holds every source of the facility file: the authored files
and the imported/<layer>/ directories the importers write. With
machine:, the machine facts come from a
machine repository instead.
Describe your facility walks the tree file by file.
osprey build reads the tree and writes the facility file and its views into
the render, never back into data/facility/:
build/
facility.json the facility file
data/channel_limits.json the limits view
data/facility_facts.json the facts view
data/facility_facts.md the facts view, as markdown
data/simulator/ the simulator view and its decks
data/pyaml/<model>/ the pyAML view, per served model with a measurement file
data/graph/facility.ttl the graph view
data/channel_databases/graph.duckdb the channel search index, when the profile has a graph store
data/channel_finder/<mode>.json the channel-finder view, in every mode but graph
data/bluesky_devices.yml the device view, when Bluesky is configured
data/benchmarks/queries.json the benchmarks view, when a benchmark dataset is configured
osprey facility show prints the facility the tree builds and each view’s
path. What a scenario file holds is in Scenario files.
Convention directories#
Put a file in the directory that matches what it is, and the build carries it into the project. Where each one lands is fixed. Skills, agents, rules, output styles are also selected by name (see Naming your own skills, agents, rules and output styles), and hooks by the declaration that wires them (see Custom hooks); everything else lands in every render.
Put it here |
It lands here |
One entry is |
|---|---|---|
|
|
a |
|
|
a directory with a |
|
|
a |
|
|
a |
|
|
a |
|
|
a script, usually |
|
|
a directory named for one operator, plus one shared |
|
|
a directory per server |
|
|
a directory per compose service |
|
|
a directory named for one watchdog (see The watchdogs: block) |
|
the build root ( |
any file, mirrored verbatim |
Nested paths inside a markdown directory are preserved, so
commands/orbit/correct.md stays namespaced. Skills, MCP servers, services
and per-user context copy as whole directories — the directory is the entry,
and a build replaces it wholesale.
Naming your own skills, agents, rules and output styles#
These four render only where a list names them, like the library artifacts in the same list. Name one with its directory as a prefix:
skills:
- diagnose # a library skill
- skills/beam-check # skills/beam-check/ beside profile.yml
output_styles:
- output-styles/terse # the directory's spelling, hyphenated
hooks:
- hooks/osprey_limits.py # only a file replacing an OSPREY hook
profile.yml’s lists select for the deployment and every login, a login adds
to them, and a lists: own login’s lists are its whole selection. A bare entry always means
OSPREY’s artifact. A file named like one (rules/facility.md) replaces it
only where its path, rules/facility, is named: there it counts as that
artifact for wiring, checks and the brief, and supplies only the content.
Listing both in one render is a build error. A path naming no file fails the build; a file no list names
reaches no render, and the build warns. osprey init names the facility
description it seeds by its path. On a profile whose lists name nothing by path
yet, osprey init --revalidate turns a bare entry into the path wherever the
repo ships the file, and names every other unnamed one in profile.yml and
each login, so its renders stay as they were.
A hooks: list names a hooks/<file> only to replace an OSPREY hook; any
other entry is refused. Your own hooks are wired, and copied, by their
claude_code.hooks declaration (see Custom hooks).
A file you ship this way is registered as yours in the project: later
re-renders never overwrite it, and cleanup never removes it. Name a file after
something the framework also renders (rules/safety.md) and list its path
(rules/safety) instead of the bare name: yours wins in that render.
Ownership is derived from what the build actually copied, after exclusions are applied — there is no list to maintain. An artifact the profile excludes is not copied and therefore not owned, so the framework’s own version renders in its place.
A misspelled directory is silent
rule/ is not rules/, and nothing reads it. The build warns about
unrecognized top-level entries in a profile for exactly this reason — read
that warning rather than wondering why an artifact never arrived.
Paths the profile may not write#
project/ is the escape hatch for anything without a home in the table above.
It cannot write paths the build already owns, because each of those has its own
channel:
Path |
Written by |
|---|---|
|
the profile’s |
|
|
|
the build, from your |
|
the profile’s |
|
the profile’s |
|
the profile’s own |
|
the build itself |
|
the build, from |
|
the build: the pyAML view, per served model with a measurement file
( |
A profile that targets one of these is rejected at build time, with the owning channel named. The same refusal applies to a claim (below).
This table is about build channels — which part of the profile is allowed to produce a file. A separate question is which files the running agent may not rewrite, whatever channel produced them; that is the protected set, and it is neither a subset nor a superset of this one.
hook_config.json is the one worth understanding: the write-safety hook reads
it to decide what counts as a hardware write. A hand-written copy would be
treated as yours and never regenerate, quietly freezing that decision.
A profile is self-contained#
Everything a profile contributes lives inside the profile directory. That is what keeps a build reproducible: clone the deployment repository anywhere, and the same project renders.
That includes its name. The compose project, the volumes, the images and the
login renders are all named from the tracked project_name: field, never
from the folder the clone sits in, so a clone under any folder name renders and
deploys the same deployment. The flip side is that two clones on one host are
the same deployment until one of them says otherwise. A second clone that runs
beside the original declares its own name in a variant overlay
(One repository, several hosts); without one, osprey up refuses to start over
the original’s containers.
The build holds the convention directories to it. An entry that is a symlink
resolving outside the profile is refused, with the remedy — copy the target in
instead. osprey scaffold claim refuses the same shape before it moves
anything, because a claim that carried such a link into the profile would
report success and then break every later build.
Note
The check catches the mistake, not an adversary: copies dereference symlinks, and the check follows directory links the way the copy does; a target can still change between the check and the copy. Read it as the rule the build holds you to, not as a boundary it enforces.
data: is a path the profile names, not material the build finds by
convention. It resolves against the profile directory and must resolve inside
the repository, as must every file the profile extends. osprey validate
and osprey build refuse a profile that reads anything outside the
repository, before anything is installed, naming the path. The resolved tree is
folded into the profile hash, so editing it reports the built project as out of
date. machine:, the facility directory of a mounted machine repository,
resolves and is folded the same way.
Taking ownership of a framework artifact#
Everything the build renders is framework-managed: every osprey build
refreshes it from the installed OSPREY version, so framework fixes reach your
project on their own — and an edit made in place is overwritten the next time.
Claiming is how an edit survives.
To customize something OSPREY generates — a rule, an agent, a service template — move it into the profile:
cd my-facility
osprey scaffold claim rules/safety
osprey scaffold claim agents/channel-finder
osprey scaffold claim services/postgresql
The artifact is moved out of build/ and into the matching convention
slot of the repository’s profile — rules/safety lands at
<profile>/rules/safety.md, services/postgresql at
<profile>/services/postgresql/. A claimed skill, agent, rule, output style
or hook is named by its path (rules/safety) wherever profile.yml or a
login listed its bare name. Edit it there, then rebuild:
osprey build
The next build copies it back and registers it as yours. There is no YAML to edit — ownership is derived from what the build copied, not declared.
osprey scaffold list # what is framework-managed, what is yours
osprey scaffold diff rules/safety # how far your copy has drifted
osprey scaffold unclaim rules/safety # give it back to the framework
unclaim holds only until the next build: while the profile still supplies the
file, the build copies it in and registers it again. To give an artifact up for
good, delete it from the profile.
A claim is refused, with the reason, when:
the project names no profile to claim into (nothing would keep the edit);
the artifact is generated, not authored —
hook_config.json,settings.json,.mcp.json,CLAUDE.md. The message names the config key that does control it;the artifact is a symlink, or holds one pointing outside itself — a profile must be self-contained;
the profile slot is already occupied. A claim never overwrites profile material.
The web terminal offers the same move from the browser: its scaffold gallery overrides a framework-generated artifact by claiming it for you (see Run the Web Terminal).
Before reaching for a claim, check whether a config key or an environment variable already covers your need — most service knobs (ports, images, credentials, retention) are configurable without owning the template.
A facility artifact kind and its viewer#
The sidebar and gallery group artifacts by base form (plots, trends,
tables, documents, dashboards, images, data). A kind of
your own is an extension type that conforms to one of them; a writer tags an
entry with it (kind="beam_study" on the store’s save). Declare it in the
profile:
config:
artifact_server.extension_types.beam_study:
{label: Beam study, base_form: plots, viewer: viewers/beam_study.mjs}
and ship the viewer through project/ (here
project/viewers/beam_study.mjs). The viewer is an ES module exporting
render(container, artifact, ctx), with ctx = {fileUrl, theme, tokens};
it draws only into container. A viewer that fails to load, lacks
render or throws falls back to the base form’s viewer. What osprey
build refuses is listed under artifact_server: — the workspace gallery’s extension types.
Custom hooks#
A hook is a script the agent runs at a defined moment — before a tool call, at
session start. Ship yours through hooks/:
my-facility/
hooks/
facility_guard.py
A config: key naming the event it fires on wires it, and the script is
copied to .claude/hooks/facility_guard.py in every render that declaration
is in force in — and in no other:
config:
claude_code.hooks.PreToolUse:
- hook: facility_guard.py
matcher: "mcp__controls__.*" # optional — defaults to every tool call
timeout: 10 # optional — seconds, defaults to 60
claude_code.hooks.SessionStart:
- facility_banner.py # shorthand when there is nothing to qualify
Valid events: PreToolUse, PostToolUse, PostToolUseFailure,
UserPromptSubmit, SessionStart, Stop, StopFailure, SessionEnd,
SubagentStop, Notification, PreCompact.
An undeclared hook never runs
Without a declaration the script reaches no render, and the build warns.
Never list it in hooks: instead: that list names OSPREY’s hooks, and a
hooks/<file> there only replaces one.
Guards are a floor. Every PreToolUse hook in force on the deployment’s
render — OSPREY’s (approval, writes-check, limits, memory-guard) or
one profile.yml declares — reaches every login render, inert where no tool
it matches is present. A login adds guards; it never drops one by leaving it
out or by a --set edit. A declaration on any other event reaches a lists: add login with
profile.yml’s config, and a lists: own login only when its own
config: declares it.
Declared wiring is added to the framework’s, never put in its place. Your declaration cannot remove, alter, or displace anything the generated settings already wire — the write-safety gate and the rest render unchanged. Every hook whose matcher fits runs, so a declared hook is one more check on top of the framework’s, never a substitute for one.
A declaration is refused at build time, with the reason, if it names a hook the
resolved profile does not ship, a built-in hook whose wiring the framework
already owns, or anything outside hooks/.
OSPREY’s own helper files ship beside the hooks that need them and are not named
in hooks:. A facility hook that wants a helper ships its own copy under
hooks/, or claims the rendered one with osprey scaffold claim
hooks/hook-log after a build that rendered it.
Unwiring a hook in a tier#
The wiring is a config: key, so a tier overrides it — but you have
to use the right spelling:
config:
claude_code.hooks.PreToolUse: null # this event now wires nothing
claude_code.hooks: {} # or: unwire every event at once
Either form also stops the script being copied into that render.
An empty list does nothing
A tier’s lists merge additively with the profile’s, so
claude_code.hooks.PreToolUse: [] adds no entries and leaves the hook
wired — silently. null is the spelling that works.
The same holds for a profile or variant overlay that exclude:s a
shipped hook: it must unwire it in the same file, because the build
refuses a declaration pointing at a hook that was dropped. That refusal
prints the exact null line to paste, so if you reach for [] on an
excluded hook the build hands you the correction rather than letting it
pass.
Replacing a built-in hook#
Shipping and declaring behave differently for the framework’s own hooks.
Shipping a file named for a built-in replaces it where a hooks: list
names its path: hooks/ is keyed by filename, because that is what the
generated settings run. The built-in writes-check hook is
osprey_writes_check.py, so listing hooks/osprey_writes_check.py in place
of writes-check makes your file the one the agent runs, wired exactly where
the built-in was. This is the one hooks/<file> a list accepts.
Declaring a built-in hook is refused. The framework wires its own hooks from
the profile’s hooks: selection, so a declaration naming one would invoke it
twice. Select or unselect a built-in through hooks:; never through
claude_code.hooks. A built-in guard the deployment selects reaches every
login all the same, in the spelling profile.yml gives it.
Logins#
Some presets give each operator their own web terminal. Every card on the
landing page opens a login: one file in tiers/, laid over
profile.yml and rendered as its own project. For those presets
(demo), osprey init writes six:
my-facility/
profile.yml
data/
tiers/
readonly.yml # a read-only terminal
readwrite.yml # a write-capable terminal
admin.yml # the one terminal that may edit the deployment
logbook.yml # logbook research, shared
knowledge.yml # facility knowledge, shared
channel-finder.yml # channel search, shared
A login file says what its card’s agent is: name, model,
claude_md_template, default_panel, channel_finder_mode, the
hooks, rules, skills, agents, output_styles,
web_panels and mcp_servers lists, panel_presets, config:,
the per-render keys extra_mounts, seed_base and image, and the
provenance: block osprey init writes. A deployment fact — the
connector, the provider, port_base, a service block, data:,
machine:, services: — is refused on a login, naming profile.yml as
its home, and so are extends: and exclude:. A login never subtracts.
lists: says how the file’s lists meet the deployment’s:
lists: add(the default) adds them by name, and itsconfig:keys win.readonlyholds chieflycontrol_system.writes: never;adminthe privileges the profile deliberately withholds.lists: owntakes the lists,name,default_panel,claude_md_templateandchannel_finder_modefrom the file alone; nothing the deployment selects is inherited. Itsmcp_serversare added to the deployment’s, but none of the deployment’s server switches reach it, so the file switches off each server it does without. The guards still reach it (see Custom hooks). The bundledlogbook,knowledgeandchannel-finderlogins are written this way.
A login’s write posture is its tier, control_system.writes
(Privilege Tiers). A login named by
modules.web_terminals.shared opens from a shared card everyone on the
roster can use, and a shared card never writes: the build seals that render
control_system.writes: never, closes every deployment-edit door and adds
the writes-check hook, whatever its file says; no --set edit unseals
it.
apps: picks the applications the deployment lists in profile.yml that
this login’s card shows: apps: {<name>: {shown: true}}. A listed
application is shown under lists: add and hidden under lists: own
unless the entry says otherwise. Whether one is on is profile.yml’s to say,
never a login’s. panel_hidden: true beside shown: true keeps the
application’s panel off the sidebar until someone adds it from “+ Add panel”. A shown application writes only where the login’s tier arms
it — asked or allowed, never never — and then only on a machine
whose switch the operator has turned on; whether a write still asks for
approval is decided per write at run time.
A login runs the deployment’s model unless its file names its own with a
top-level model:, such as a cheaper model for a research card:
# tiers/logbook.yml
model: claude-sonnet-5
The provider is always profile.yml’s: a login may name its own model, never
its own provider. As for profile.yml, an id the provider’s models list
does not carry is used as written, and the build warns that the provider does
not list it. A login never spells config: claude_code.default_model; the
build renders that key from model: and refuses it in the file that spells
it.
Edit a file to change what its terminals can do, and see the merged result with:
osprey validate tiers/readonly.yml
The file name is the name: users[].tier, default_tier and shared:
each pick a file in tiers/. Each renders to
build/<project_name>-<name>. osprey up renders nothing: a login missing
from build/ stops the start and points at osprey build.
osprey scaffold tiers writes the preset’s login files again, leaving any
you edited alone. A repository that still keeps a login in apps/ moves it
with osprey init --revalidate (CLI Reference).
Removing something a profile brings#
exclude: subtracts entries, and the spelling decides what it removes:
exclude:
skills:
- writing-bluesky-plans # bare: stop selecting the built-in skill
agents:
- agents/channel-finder # qualified: drop the profile's own file
A bare name unselects a built-in artifact, so it is no longer installed. A
qualified name (<directory>/<name>) omits the profile’s own file for that
name — which is how a profile that wants the stock version back gets it: drop
your shadowing copy, and the still-selected built-in renders again.
Bare exclusion accepts skills, rules, hooks, agents,
output_styles, web_panels and dependencies; qualified exclusion
accepts any convention directory. Excluding something that is not there is a
silent no-op.
config: is the one key under exclude: whose value is a mapping rather
than a list. Each entry names a list-valued config: key by its dotted
spelling and lists what to take out of it:
exclude:
config:
deployed_services:
- mongodb # this layer deploys everything else
This is how a profile deploys fewer services than the one it extends. Lists
under config: union across extends and across a host-variant overlay,
so an overlay cannot state a shorter list; it names the entries it drops instead.
exclude: belongs to profile.yml and its variant overlays; a login that
spells it is refused.
A key the profile does not carry is a silent no-op; a key that holds anything
other than a list is refused.
An excluded web_panels entry renders no tab, whatever the render still
inherits about that panel under config:. exclude: takes entries out of
lists, never scalars — a web.panels.okf.label or a custom panel’s
web.panels.<id>.url the base profile set is still in the render —
but web_panels is what shows a tab: the build writes enabled onto every
web.panels.<id> block a render carries, true for a selected panel and
false for any other, and the web terminal, the health probe and the
credential grants all read that one flag. The facts stay so the Reach Contract
can keep copying a host’s addresses into the logins that do select the tab.
A config: line that says web.panels.<id>.enabled and contradicts the
selection is refused at validation, as two spellings of one fact disagreeing.
Excluding a declared hook takes one more line: the same delta has to unwire
it with claude_code.hooks.<Event>: null, or the build refuses the wiring
that points at a dropped file. See Unwiring a hook in a tier.
The mistake worth knowing about
Use the bare spelling on a name your profile also ships a file for, and the exclusion does nothing visible: the built-in is unselected, but your file still renders, so the project comes out byte-identical and the build succeeds. The build warns when it sees this and names the qualified spelling that would actually drop the file. Read that warning rather than trusting a green build as proof the exclusion took.
Note
exclude: carves a tier by removing capability. When the boundary you
want is “may not write,” prefer flipping the enforcement switch instead —
the bundled readonly tier differs from its
write-capable sibling only on the tier key, control_system.writes,
leaving the tool surface identical (see
Privilege Tiers and Who May Write).
To keep the bluesky server on while hiding an individual plan, set
bluesky.excluded_plans instead:
bluesky:
excluded_plans: [orm]
The named plan is then invisible to the agent and non-runnable. The same
block’s plan_dir key does the opposite — it installs a directory of your
facility’s own plans; see Write Your Own Plans.
The third piece, the file listing the devices those plans may drive or record, is not a profile key: the build writes it from your facility file. Its format is in Write Your Own Plans.
One repository, several hosts#
A test stand and a control-room machine can run the same deployment and still need different settings — another hostname, other ports, a different theme. Keeping two copies of the repository in step is the thing to avoid. Keep one profile instead, plus a small overlay per host:
my-facility/
profile.yml # what every host shares
profiles/
teststand.yml # what the test stand changes
control-room.yml # what the control room changes
.env.variant # which of the two THIS host builds
An overlay holds only the differences, in the same spelling profile.yml
uses:
# profiles/teststand.yml
config:
deploy.fqdn: teststand.example.org
web.theme: dark
Each host names the one it wants in .env.variant at the repository root:
echo OSPREY_PROFILE_VARIANT=teststand > .env.variant
osprey build merges that overlay over profile.yml before it renders
anything, and says which variant it used in its output. Logins are rendered
for the same host, so a stack cannot come up half-configured for another one: each
sees the overlay through the profile.yml it merges over. An overlay that adds a
services: entry therefore adds it to the deployment, and the login renders
stay attached to it like any other service the deployment runs.
The overlays are committed: which hosts a deployment has is part of what the
deployment is. The choice between them is not — .env.variant is covered by
the generated .gitignore along with the rest of the .env* family, so
each host keeps its own answer, and a build warns if the file ever does get
committed. There is no command-line flag for this today; the file is how a
host chooses. If one is added later, a variant named on the command line will
win over the file.
Three cases worth knowing about:
No setting, or an empty one. The build renders
profile.ymlas tracked and the overlays sit unused. This is also what a host that has never heard of variants does, so addingprofiles/to a repository changes nothing until a host selects something.A name the repository has no file for. The build stops and lists the names that would work. The previous
build/is left as it was, as with every other refusal.Switching variants. Rebuild.
build/is the render of one host’s profile, and editing the setting does not re-render anything by itself — but switching.env.variant(or editing the selected overlay) marks the existingbuild/out of date, soosprey upnames the stale render instead of starting it silently.
Two checkouts on one host#
The same mechanism covers a second checkout on the same host — a scratch
clone beside the deployment, or a worktree. Both checkouts read the same
tracked project_name:, so without an overlay they are one deployment: same
compose project, same volumes, same image tags. osprey up in the second
checkout refuses while containers under that name were created from the
first, and names both ways out (see Two checkouts of one repository on one host).
To run the second copy beside the first, give it its own name in an overlay and select it in that checkout only:
# profiles/scratch.yml
project_name: my-facility-scratch
echo OSPREY_PROFILE_VARIANT=scratch > .env.variant
osprey build
project_name is a top-level field, so the overlay sets it the way it sets
any other. The scratch copy then has its own containers, volumes and images,
and starts with empty data. A clone that keeps the tracked name is the same
deployment and shares its volumes by that declaration; the refusal guards
against two copies running at once, not against moving a checkout.
The port block is the other thing two copies on one host share; move it in the
same overlay with config: deployment.port_base.
An overlay adds and replaces; it does not subtract. Lists are merged rather
than swapped, so use exclude: to take something away
on one host — that works in an overlay like anywhere else, and
exclude: {config: {deployed_services: [...]}} is how one host deploys
fewer services than the profile it builds from.
Secrets#
API keys and service credentials live in one file: the .env at the root of
the deployment repository, read together with the committed .env.shared
beside it. Environment Variables (the .env chain) is that pair in full — which of the two
wins, what a deploy writes back into them, and the machine-written .env*
files that go with them.
Seeding, once#
osprey init seeds the new repository’s .env from your shell, and only
the keys of providers this profile actually references. Keys you exported for
other providers are named in the summary rather than copied in, so you can tell
“seen and not needed” from “lost”. If your shell exported nothing usable, no
.env is written at all (an empty secrets file reads as a configured one);
start it yourself:
cp .env.example .env
The only moment a shell export reaches the repository unasked
It happens once, at osprey init, and what it took is written under a
“Seeded by osprey init from your shell” heading — so the file itself
records where each value came from. No build reads your environment for
secrets, and a later build never re-reads your shell. (osprey up will
seed a missing .env with this deployment’s provider key, but only on an
interactive terminal and only if you say yes at the prompt — see
Environment Variables (the .env chain).)
The practical consequence: once the repository has a .env, exporting a
key does not get it in — no writer ever overwrites a value already on file.
Put it in .env yourself.
Who else writes to .env#
osprey up appends minted credentials to the file and leaves a value
already on file alone; Environment Variables (the .env chain) has what it writes and why.
Profile YAML reference#
Every key profile.yml accepts — the field table, config: overrides, MCP
servers, tool permissions, services, va_archiver, lifecycle commands,
env, dependencies and the execution environment — is in
Build Profile — profile.yml.
The watchdogs: block#
A map from a watchdog’s name to its definition, with any number of entries. The name is
lowercase letters, digits, - and _, starting with a letter or digit, and it names the
directory watchdogs/<name>/ beside profile.yml. That directory holds
instructions.md and, optionally, references/. A rendered project carries only the
enabled entries and their directories; with none enabled, it carries neither the block nor the
trigger hook. Safety watchdogs has the steps.
Key |
Engine |
Default |
Meaning |
|---|---|---|---|
|
both |
required |
|
|
both |
|
Run it on every prompt. An enabled watchdog needs its instructions, and needs
|
|
decision |
required |
A list of |
|
decision |
|
The summed probability of the flag options at which it flags, between 0 and 1, exclusive. Not calibrated. |
|
agent |
|
Read tools beyond those it always has. An entry is a tool name, optionally ending in
|
|
agent |
|
A model name; |
|
agent |
|
Seconds one run may take. |
|
agent |
|
Dollars one run may spend. |
A key the entry’s engine does not read fails the build. A profile that inherits a watchdog
through extends does not inherit its files, so it may carry the entry disabled as it stands
and must add the files itself to enable it.
Building#
osprey build [OPTIONS]
Run it with no arguments, anywhere inside the deployment repository. It walks up
to profile.yml and renders the whole build/ zone from it.
Options
|
Stream lifecycle step output in real time. |
|
Skip |
|
Skip venv creation and dependency installation (CI mode); deployment-package wheels are still built, for the image. |
|
Override |
|
Render a dev build: bake the local OSPREY checkout into the service images instead of the published release. |
|
Deployment repository to act on (default: the nearest |
Settings are changed before the build, not during it
osprey build takes no configuration overrides. Change a setting with
osprey set, which writes it into profile.yml — comments and
formatting intact — and then build. osprey init --set makes the same
edit before the file exists. Either way the value at the key is replaced,
so a list you state is the list the profile holds. The profile always
describes what the build will produce, so there is no layer that vanishes
afterwards.
Every build wipes and re-renders build/ and preserves what you own: the env
chain (.env.shared and .env), var/, and the repository’s .git.
It never touches the source zone — only osprey init --force replaces that.
Examples
# See what presets ship
osprey init --list-presets
# Create the deployment, then render it
osprey init my-facility --preset demo
cd my-facility
osprey build
# Change a setting, then carry it through to build/
osprey set model=claude-sonnet-5
osprey build
# Render another repository's build/ without cd-ing to it
osprey build --repo ~/deployments/my-facility
Checking a profile without building#
osprey validate
osprey validate tiers/readonly.yml
Resolves the profile and runs the full consistency check — convention directories, the data tree, service templates, lifecycle steps, environment variables — reporting every problem found, not just the first.
The profile is yours to edit. No difference from the preset it was
materialized from is refused or listed. When the preset bundled with your
OSPREY has changed since the repository last took it, validate and
osprey build print one line saying so.
Upgrading OSPREY#
pip install -U osprey-framework
osprey init --revalidate # applies the presets' changes, prints the diff
# review the diff; drop any change you do not want; commit
osprey validate
osprey build
osprey init --revalidate applies only what the presets changed since the
repository last took them, and only where you kept the preset’s old value. Your
own edits are left alone, and anything you deleted stays deleted. A change you
drop from the diff before committing is not offered again; to take it later,
copy it from the preset by hand.
What the build does#
Find the repository’s
profile.yml(the nearest one at or above the working directory, or the one under--repo) and read it.Resolve and validate the profile, including any tier merged over it.
Check
requires_osprey_version; abort if unsatisfied.Start the new render in
build/.tmp. Until it succeeds, the previousbuild/(apart from its venv) stays as it was, so a failed build leaves the last good one in place.Run
pre_buildcommands.Create the project venv and install OSPREY plus the profile’s dependencies.
Render the base template and the profile’s
data/tree. No env file is carried in: the repository’s own.env.sharedand.envstay where they are, and the containers are handed them at start time.Apply the
config:overrides.Copy service templates and inject the profile’s own services.
Apply the convention directories, and register what was copied as yours.
Persist
mcp_servers:intoconfig.yml.Stamp the manifest (
.osprey-manifest.json), including the fingerprintosprey upcompares the profile against before it starts anything.Re-render the agent artifacts against the complete config, and validate that every tool an agent declares is backed by a permission.
Run
post_buildandvalidatecommands on the project venv, then swap the finished render in asbuild/.
The venv is created before rendering so templates can reference the resolved Python path. The generated project runs standalone — nothing reaches back to the profile at runtime.
What gets generated#
my-facility/build/
├── .claude/
│ ├── agents/ # built-ins, plus anything from the profile's agents/
│ ├── rules/ # built-ins, plus the profile's rules/
│ ├── hooks/ # hook scripts, plus the generated hook_config.json
│ ├── skills/
│ ├── output-styles/
│ └── settings.json # permissions, hook wiring, model config
├── .mcp.json # MCP server configurations
├── CLAUDE.md # generated system prompt
├── config.yml # config with the profile's overrides applied
├── data/ # the profile's data tree, materialized
├── _mcp_servers/ # facility server code from the profile
└── .env.example # every variable this deployment reads, no values
Which built-in agents, rules, hooks and skills are installed comes from the
agents:, rules:, hooks: and skills: lists in profile.yml.
Your own files come from the convention directories and are marked as yours.
Troubleshooting#
“No OSPREY deployment repo found: no profile.yml in … or any parent
directory.” — osprey build reads the profile.yml of the deployment
repository it runs in, and found none at or above the working directory. Run it
from inside the repository, point at one with --repo PATH, or create one with
osprey init <name> --preset <NAME>.
“The … preset has changed since this repo last took it” — a note, not an
error. The preset your profile came from has changed in the OSPREY release you
run. Your deployment does not change with it, because the profile inherits
nothing. Run osprey init --revalidate to take the changes (see
Upgrading OSPREY).
“This repo predates preset tracking” — a note, not an error. The repository
was made by an OSPREY release that kept no copy of what its preset produced.
Run osprey init --revalidate once, and commit what it writes.
“Profile convention directories are invalid” — a convention directory has
the wrong shape: a .md directory holding something else, or a skill that is
a file rather than a directory. Every problem is listed at once.
“… outside the repository. Move it into the repository.” — an input, or a link inside one through any number of hops, resolves outside the repository; copy the target in (see A profile is self-contained).
“web-terminal-context/<name> is a file” — that directory holds one
directory per operator, plus the shared base.md. Move the file into the
directory of the operator it belongs to, or rename it to base.md if it is
the text everyone starts from (see The shared web-terminal baseline).
“project/ mirror writes N build-owned path(s)” — the mirror targets a path another channel owns. The message names the channel, and the exact move where one exists.
“Repo root has N unrecognized top-level entry/entries” — a warning, not an error: an entry no channel renders into the project. Usually a typo of a convention directory name. A container image still carries it, as part of the repository’s source.
“Unknown profile key(s): ‘overlay’” — a profile has no overlay
section. Move the files into the convention directory that matches what they
are (see the table above), or into project/ for anything without one.
“is already an OSPREY deployment repo” — osprey init will not lay a
source zone over one that is already there. To re-render the project, run
osprey build in the repo: it wipes and re-renders build/ and
leaves the source zone alone. To replace the source zone itself from the
preset, re-run osprey init --force — which rewrites profile.yml,
data/, tiers/, apps/, triggers.yml, web-terminal-context/,
watchdogs/ and .env.example, losing any edit to them. In
providers.yml it resets the entries OSPREY ships and keeps the ones you added.
“already exists, is not empty, and is not an OSPREY deployment repo” — a
deployment repo is one directory that holds nothing else, so osprey init
will not write into a directory that is already someone’s. Choose an empty or
new path; --force does not apply here.
“OSPREY X does not satisfy requires_osprey_version” — upgrade OSPREY, or relax the constraint in the profile.
See also
- CLI Reference
Complete CLI command reference
- Add an MCP Server
How to build custom MCP servers for OSPREY
- Container Deployment
Container deployment after building