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/ zone

  • What lives in a profile: the convention directories, data/, secrets, logins

  • Moving an artifact you want to own out of build/ and into the profile

  • Shipping 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 to running containers A bundled preset is copied once into your profile.yml by osprey init; osprey build renders the derived build zone from it, and osprey up starts the containers. osprey init osprey build osprey up preset bundled with OSPREY profile.yml yours · in git build/ derived · never edited containers the running stack
  • Preset — a bundled starting point, shipped inside OSPREY (src/osprey/profiles/presets/). Run osprey profile presets to list the presets that ship.

  • Profile — the profile.yml at 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/ zone osprey build renders. 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

rules/

.claude/rules/

a .md file

skills/

.claude/skills/

a directory with a SKILL.md

agents/

.claude/agents/

a .md file

commands/

.claude/commands/

a .md file

output-styles/

.claude/output-styles/

a .md file

hooks/

.claude/hooks/

a script, usually .py

web-terminal-context/

docker/web-terminal-context/

a directory named for one operator, plus one shared base.md

mcp_servers/

_mcp_servers/

a directory per server

services/

services/

a directory per compose service

watchdogs/

watchdogs/, for enabled watchdogs only

a directory named for one watchdog (see The watchdogs: block)

project/

the build root (build/)

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

config.yml

the profile’s config: block

.claude/settings.json

config: keys — claude_code.permissions, claude_code.hooks

.claude/hooks/hook_config.json

the build, from your mcp_servers: and control_system.write_tools

.mcp.json

the profile’s mcp_servers: block

CLAUDE.md

the profile’s claude_md_template: key

.env / .env.example

the profile’s own .env file and env: keys

.osprey-manifest.json

the build itself

data/channel_limits.json

the build, from data/facility/limits.yaml

data/pyaml/<model>/

the build: the pyAML view, per served model with a measurement file (data/facility/measurement/<model>.yaml)

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.

The shared web-terminal baseline#

web-terminal-context/ is the one convention directory that accepts a loose file: base.md, the text every operator’s terminal starts from. It sits beside the per-operator directories and rides the same channel, landing at docker/web-terminal-context/base.md.

Three layers stack, in this order:

  • the framework’s fallback. Every build installs a generic base.md into the rendered project, so a deployment always has one.

  • the profile’s own copy. A web-terminal-context/base.md in the profile is copied over that fallback. osprey init materializes one — from the app template’s text where it ships its own, otherwise the framework’s — so the baseline is in your repository from the first minute, where you can read and edit it.

  • each operator’s ``extra.md``. At seed time the baseline and that user’s web-terminal-context/<user>/extra.md are concatenated, and the result becomes their CLAUDE.md.

Unlike the per-operator directories, the baseline is not roster-derived. It is copied on every build, including a login render that has no roster at all, and osprey init writes it whenever the profile stands up web terminals (modules.web_terminals.enabled) — even when the roster is still empty, so a profile that names no operators yet still starts from text it can see. A profile with no web-terminal module gets no web-terminal-context/.

The profile drops it with the ordinary convention vocabulary, qualified like any other profile-shipped file:

exclude:
  web-terminal-context:
    - web-terminal-context/base.md   # the framework fallback renders instead

A login render has no web terminals of its own, so it resolves an empty roster and copies no operator directories.

To keep the baseline in the deployment but leave it out of one login’s terminals, set seed_base: false at the top of its file in tiers/: its users are seeded from their own extra.md alone.

base.md is the only loose file

Any other file directly in web-terminal-context/ is refused at build time, and the message names both routes: move it into the directory of the operator it belongs to, or rename it to base.md if it is the text everyone starts from. Directory names here are matched against the resolved roster, so a directory invented to hold a stray file is skipped as an operator who has left — and nothing in it would ever be read.

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 its config: keys win. readonly holds chiefly control_system.writes: never; admin the privileges the profile deliberately withholds.

  • lists: own takes the lists, name, default_panel, claude_md_template and channel_finder_mode from the file alone; nothing the deployment selects is inherited. Its mcp_servers are 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 bundled logbook, knowledge and channel-finder logins 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.yml as tracked and the overlays sit unused. This is also what a host that has never heard of variants does, so adding profiles/ 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 existing build/ out of date, so osprey up names 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

engine

both

required

decision or agent.

enabled

both

false

Run it on every prompt. An enabled watchdog needs its instructions, and needs turn-state in hooks:.

options

decision

required

A list of {id, text, flag}, with at least one flag: true and one not. text is what the operator reads.

threshold

decision

0.5

The summed probability of the flag options at which it flags, between 0 and 1, exclusive. Not calibrated.

tools

agent

[]

Read tools beyond those it always has. An entry is a tool name, optionally ending in * or .*; one that reaches a write tool fails the build.

model

agent

null

A model name; null is the deployment’s own.

timeout_s

agent

90

Seconds one run may take.

max_cost_usd

agent

0.25

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

-s, --stream

Stream lifecycle step output in real time.

--skip-lifecycle

Skip pre_build, post_build, and validate; deployment-package wheels are still built and installed.

--skip-deps

Skip venv creation and dependency installation (CI mode); deployment-package wheels are still built, for the image.

--runtime-root PATH

Override project_root in the rendered config, for a build whose output runs somewhere other than where it was made.

--dev

Render a dev build: bake the local OSPREY checkout into the service images instead of the published release.

--repo DIRECTORY

Deployment repository to act on (default: the nearest profile.yml at or above the working directory).

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#

  1. Find the repository’s profile.yml (the nearest one at or above the working directory, or the one under --repo) and read it.

  2. Resolve and validate the profile, including any tier merged over it.

  3. Check requires_osprey_version; abort if unsatisfied.

  4. Start the new render in build/.tmp. Until it succeeds, the previous build/ (apart from its venv) stays as it was, so a failed build leaves the last good one in place.

  5. Run pre_build commands.

  6. Create the project venv and install OSPREY plus the profile’s dependencies.

  7. Render the base template and the profile’s data/ tree. No env file is carried in: the repository’s own .env.shared and .env stay where they are, and the containers are handed them at start time.

  8. Apply the config: overrides.

  9. Copy service templates and inject the profile’s own services.

  10. Apply the convention directories, and register what was copied as yours.

  11. Persist mcp_servers: into config.yml.

  12. Stamp the manifest (.osprey-manifest.json), including the fingerprint osprey up compares the profile against before it starts anything.

  13. Re-render the agent artifacts against the complete config, and validate that every tool an agent declares is backed by a permission.

  14. Run post_build and validate commands on the project venv, then swap the finished render in as build/.

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