Build Your Own App#
This page takes an app from nothing to running on your deployment. It starts
from the scaffold osprey app new writes — a working app whose panel shows
one channel and whose agent tools read it and set it behind an approval — and
then goes through each part you will change to make it your own. The example
app is called corrector-trim and shows and sets one horizontal corrector’s
current; use any name of lower-case letters, digits and dashes.
What You’ll Learn
The six commands from
osprey app newto a panel in the sidebarWhat each file of the scaffold does and where your code goes
How the manifest’s
approvalentry turns a tool into a write the operator approvesWhich logins show the app, and which may write with it
How to give the agent a skill, and the same reach as the operator
How an app carries a subagent, and which parts an app can leave out
Prerequisites: a deployment repository made with osprey init
(Build Profiles) that builds and starts; Node and npm on the
machine where you run osprey app check, for the panel’s JavaScript
checks and tests. Read Build Your Own OSPREY Apps first for what the parts of an app are.
Make it run#
1. Make it#
osprey app new corrector-trim
This copies the scaffold into apps/corrector-trim/, rewrites every name in
it (scaffold-app to corrector-trim, the Python package to
corrector_trim), and lists the app in profile.yml:
apps:
corrector-trim: {}
Listing an app is what turns it on; delete the entry to turn it off while the
directory stays. The command also adds /apps/*/panel/vendor/ to
.gitignore, for files a build fetches into a panel (Manifest keys,
vendor).
2. Point it at a channel#
The scaffold names no channel of its own — which channel to show is the
deployment’s choice. Until profile.yml gives it one, the panel says so and
a write is refused. The config: block under the app’s entry is free-form;
the build writes it to a file the backend reads at start:
apps:
corrector-trim:
config:
channel: SR:MAG:HCM:01:CURRENT:SP
In the example facility that is the current setpoint of horizontal corrector 01, in amperes, with a range of ±10 A and a readback pair the connector compares it against. Any key you put there reaches your backend the same way, so a facility-specific setting — a device list, a tolerance, a model name — goes here rather than into the code.
3. Check it#
osprey app check
This runs what osprey build checks of every listed app — the manifest,
each login’s selection, ports, pinned versions — and then what only the app’s
own source can tell: the import rule over its Python, ESLint over panel/
and its JavaScript tests under tests/. It builds nothing and prints every
violation with the app and the field it is in. The scaffold passes as copied.
The first run installs a pinned JavaScript toolchain into your user cache,
which needs npm and network access once.
An app an installed package ships (Build Your Own OSPREY Apps) is checked the same way, and
its violations name the distribution (<dist>:<module path>/<file>).
4. Build and start#
osprey build
osprey up -d
osprey build builds the app’s Python package into a wheel, renders its
container, assigns its port, writes its config file and adds the panel and
the tool server to every login that shows the app. osprey up builds the
project image with the wheel installed and starts the container with the rest
of the stack. osprey health lists it beside the other services.
5. Open it#
Open a terminal and look at the sidebar: under Apps there is a
Scaffold row — the label is panel.label in app.yml, which
osprey app new leaves for you to change to Corrector trim. Click it: the
panel shows the channel’s name, its readback and the machine the readback came
from — the one on your control-target chip. Switch the chip to another machine and the
panel follows at its next refresh.
Then ask the agent: what is corrector HCM01 set to? It calls
mcp__corrector-trim__read_channel and answers from the same backend. Ask
it to set the corrector-trim channel to 0.5 A:
with the switch for that machine off, the call is refused and the agent says to arm the switch from the chip;
at asked, an approval card appears in the chat: the app, the tool, the machine, and the line Set SR:MAG:HCM:01:CURRENT:SP to 0.5, now 0.32 — the scaffold’s prompt, filled from the call and from the backend’s state. Approve it and the backend writes through the connector;
at allowed, the write runs without a card.
Try the same on a read-only login (bob in the demo
preset): the panel shows the readback, and the agent’s write tool is denied.
6. Make it yours#
From here the app is ordinary code. The sections below go through the parts
in the order you will touch them: the manifest, the backend, the tool server,
the panel and its tests, then writes, logins, skills and subagents. Run
osprey app check as you go and osprey build && osprey up -d to see a change in the
terminal.
The manifest#
app.yml is the one file OSPREY reads about your app. The scaffold’s, as
copied:
# The starting point of a new application: one panel over one channel, one read tool,
# one write tool. The channel is the deployment's: apps.scaffold-app.config.channel.
name: scaffold-app
summary: Shows one channel of the control target and sets it on approval.
containers:
scaffold-app:
runtime: osprey
command: [python, -m, scaffold_app.server]
health: /health
drives_target: true
state: var/scaffold-app
panel:
label: Scaffold
container: scaffold-app
launch_token: true
agent_routes:
- [GET, /api/state]
- [POST, /api/write]
roster_grant: {single_user_alias: true}
tools:
module: scaffold_app.tools
read: [read_channel]
approval:
- tool: set_channel
prompt: Set {{ state.channel }} to {{ input.value }}, now {{ state.readback }}.
state_path: /api/state
bind:
state_fields:
- {field: approved_readback, key: readback}
require:
all_of: [approved_target, approved_readback]
errors:
unreachable: The panel's backend is not answering; check its container with osprey health.
refused: The value was not written. Read the channel again and ask for a new approval.
skills: [scaffold-app]
The first three blocks describe one part each:
containersThe backend.
runtime: ospreyruns the app’s Python package on the deployment’s own image, where OSPREY and its dependencies are already installed;commandis what it runs.drives_target: truegives the container the connection to the control system — without it the container cannot reach the machine.healthis the route the terminal polls to light the sidebar row.statenames a directory that survives restarts, for files the app keeps (saved plans or tables, for instance).panelThe sidebar entry: its
label, the container that serves it, andagent_routes, the backend routes the agent’s tools may call. A route withGETreads; any other method is a write route, and the terminal hands write routes to the agent only on a login that arms the app.launch_token: truemakes the write route demand a token the terminal adds on an armed login only, so nothing else inside the stack can call it.toolsThe tool server: the Python module to run beside the agent, the tools that only read, and the tools that write under
approval.errorsare the two sentences the agent sees when the backend does not answer or refuses.
Each block is optional, and so are skills and agents; an app.yml
with none of the five is refused. Without panel the app has no sidebar
row. Without containers it has no backend: a panel is refused, and so
is a write tool (an approval entry) on a login whose tier writes, since it
needs a container with drives_target: true; a config: block under the
app’s entry is refused too, since only a backend reads it. The tool server only
reads or computes and keeps nothing between calls. Anything that holds state is
a backend.
Every key is listed under Manifest keys. Unknown keys are refused, and a
key that belongs to the container’s compose file (volumes, ports,
depends_on) is refused with the place it lives instead.
The backend#
corrector_trim/server.py is a FastAPI service. Four routes matter:
GET /servespanel/index.html; the panel’s other files are served fromstatic/byconfigure_app;GET /healthanswers the terminal’s poll;GET /api/stateis what the panel and the read tool show: the channel, the readback and the machine it came from;POST /api/writeperforms the write.
Two things the backend does on every request are worth seeing in the source, because your own routes will do the same:
It answers for the login that asked. The terminal passes the login’s name
to the backend; owner_from_header reads it and owner_target turns it
into that login’s control target, the machine its chip points at. The backend
never chooses a machine itself, and the same route answers two operators from
two machines when their chips differ. Two Channel Access machines are the
exception: a process has one Channel Access context, so build_connector
refuses a second until the backend restarts.
It writes through the connector, under that login. build_connector
asks OSPREY for a connector to the target; bind_owner names whose write it
is; write_channel_checked is the write. The connector asks the write
verdict (tier, switch, session), applies the limits and records the write —
your code does none of that. A refusal arrives as ChannelWriteBlockedError
and the backend passes its sentence on.
A route that must tell the agent from the operator calls
caller_kind(request.headers), which answers agent or panel. The
terminal sets that header itself and drops any X-Osprey-Caller a request
arrives with. caller_kind trusts it only beside the launch token the
terminal adds (launch_token: true, on a login that arms the app) and
raises ValueError without it.
The scaffold adds one check of its own, and it is the pattern for every
write you add: the write request carries the readback the operator saw on the
card (readback), and the backend re-reads the channel and refuses when the
value has moved. The approval was for a write over a known state; a state
that changed since is a new decision.
Reading the machine is read_channel on the connector. For more than one
channel, read_multiple_channels. The facility description — which elements
exist, their channels, a model’s BPMs and correctors — comes from the SDK
(facility_file, read_facts, model_members,
model_response_matrix), so the app carries no facility knowledge of its
own and moves to another facility with the deployment. The Bluesky bridges the
deployment runs for a target come from bridges_for_target(target): lane
name to bridge URL, empty when none.
A backend that writes its own audit records files them under
audit_surface(): the app’s name, which its tool server’s records already
carry.
The tool server#
corrector_trim/tools.py runs beside the agent as an MCP server. register
adds one function per tool; the function’s docstring is the tool description
the agent reads, so write it for the agent: what the tool does, what each
argument means, what it answers. serve_tools(register) serves them; an
app that holds something for the server’s lifetime (a session, say) passes
on_shutdown=, which runs once when the server stops, returned or raised.
A tool does not import the backend. It calls the backend’s routes through the
terminal (_panel_call), at /panel/<app>/<route>, with the headers
agent_panel_headers provides — so the call carries the login’s name and
reaches only the routes agent_routes declares. The terminal is the one door
to the backend for the panel and the agent alike.
A write tool starts with check_approved_call. It runs the write chain for
this one call on the tool’s side — is the tool offered on this login, does the
write verdict allow it, is there an approval record for exactly these
arguments, is the approved machine still the session’s — and returns the state
values the approval bound (approved_readback for the scaffold). The tool
sends those to the backend, never what the agent typed. The approved_*
arguments in the tool’s signature exist for the approval hook to fill in; the
agent leaves them unset, and a value it sends is replaced.
make_error and ApprovalRefused are how a tool reports: an unreachable
backend becomes the manifest’s errors.unreachable sentence, a refusal the
errors.refused one, each with the detail appended.
The panel#
panel/index.html is a plain page. It loads the terminal’s
/design-system/ tokens.css, base.css and primitives.css first,
so it follows the theme, and then its own static/panel.css. Buttons,
toggles, chips and cards use the osprey-* classes from primitives.css;
panel.css holds only what is the app’s own. panel/panel.js fetches
api/state every two seconds and writes the fields into the page. Addresses are relative
(api/state, not /api/state) because the page is served under the
terminal’s /panel/<id>/ prefix.
The scaffold’s panel only shows; the write is the agent’s tool. A panel that writes — an Apply… button — posts to a write route the same way the tool does, and the terminal refuses the request on a login that does not arm the app, before it reaches the backend. Show that state rather than hiding the control: have the backend’s state say whether writes are on, and the panel say Writes are off.
The page says when it can be driven, which a browser test or a recording
waits for: index.html carries <html data-page-ready="pending">, and
panel.js imports markPageReady from
/design-system/js/page-ready.js and calls it once the first refresh has
drawn, error or not. osprey app check refuses a panel without the import.
tests/panel.test.js is a Vitest test of the page’s functions in a DOM;
osprey app check runs it. A JavaScript library the panel needs is not
committed: list it under vendor with its exact version and SHA-256, and the
build fetches it to the path you name — panel/vendor/…, which
.gitignore already covers.
Writes and approvals#
A tool under tools.approval is a write tool. The build lists it in the
tool server’s writes:, so every call is judged as a write, in this order:
The tier — the login’s
control_system.writes.neverdenies the tool outright;askedandallowedarm the app on that login (Privilege Tiers).The write switch — the operator’s position for the session’s machine, set from the control-target chip. Off refuses; asked shows the approval card and waits for a person; allowed runs without asking.
The approval entry — what the card shows and what the call is held to:
promptThe card’s text.
{{ input.<arg> }}is a call argument;{{ state.<key> }}a value of the backend’s state, fetched fromstate_pathwhen the card is built. The card also always carries the app, the tool, the machine and the switch position.state_pathThe backend route whose answer is
state. The scaffold uses its state route. An app that prepares a write in steps is better served by a route made for the card, one that answers only while there is something ready to write.display_lines_keyA key of that state holding lines to show under the prompt — one per channel for a write of several setpoints — so the operator sees every setpoint the write will make.
bind.state_fieldsValues of the state copied into the call as
approved_*fields: the readback the person saw, the plan id, a digest of the setpoints. The tool sends these to the backend, and the backend refuses when they no longer match what it holds. A key may be a dotted path into nested state (step.digest); one that names nothing leaves its field unbound.bind.input_digestsA digest over named call arguments, so the arguments the agent sends after approval must be the ones that were approved. An app recomputes a digest only through the SDK’s
canonical_jsonandinput_digest, the recipe the check itself uses.requireThe
approved_*fields a call must carry (all_of, or exactly one of eachone_ofgroup). Aone_ofgroup holds readback (bind.state_fields) names only, never a digest. A call that cannot be bound is refused, not asked.
The connector judges the write once more and records it.
Under allowed the same binding happens with no person asked: the card’s
content is stamped by the switch, and the tool and backend check it the same
way. The approver on the record is human, write_switch or
dispatch_policy.
The approval hook reads the entry from the render and never runs app code;
the tool server re-checks with check_approved_call; the backend checks the
bound values against its state. Three checks, one declaration.
Dispatch jobs. An agent run the event dispatcher starts has nobody to show
a card to. A write tool that binds the backend’s state never runs in such a
job, and deny_in_jobs: true under tools keeps a job from running any of
the app’s tools. Set it where every use of the app is an operator’s decision.
Logins#
profile.yml says which apps the deployment runs. Each login’s file under
tiers/ says which of them its card shows, and its tier says whether it may
write with them:
a login shows every listed app unless its file says otherwise; under
lists: ownit shows none it does not name (Build Profiles);a login arms an app when it shows it and its tier is
askedorallowed. On an armed login the agent gets the write routes and the panel’s launch token; on any other login the agent gets the read routes only and the terminal refuses the panel’s write requests;a shared login (
logbook,knowledge,channel-finderin the preset) arms nothing, whatever its file says.
A login’s apps.<name>.access says who on that login sees and opens the
panel, in the words a shared roster card uses (self, roster,
user:, domain:, tier:); without it, every user of the login does.
A user it does not admit does not see the panel in the list and is answered
as for an unpublished one, and the build refuses a set no browser user can
match. The agent is judged by the login alone, so the login keeps the app’s
tools and skill. The key never decides a write.
Hide an app from one login in that login’s file:
# tiers/readonly.yml
apps:
corrector-trim: {shown: false}
A login can also show an app and keep its panel off the sidebar: the agent has the tools and the skill, and the panel is one “+ Add panel” away rather than a tab at login.
# tiers/readonly.yml
apps:
corrector-trim: {shown: true, panel_hidden: true}
Skills and agent parity#
A skill is a SKILL.md the agent reads to know when and how to use a set of
tools. An app carries its own: list the name under skills: in app.yml
and write skills/<name>/SKILL.md in the app’s directory. The scaffold
ships one, which osprey app new renames with the app. The build installs
it into every login that shows the app, so the agent that has the tools also
has the instructions. A listed skill without its file, or a skill name two
apps share, fails the build. So does hooks in a listed skill’s
frontmatter, or a frontmatter that does not close on a line that is exactly
---: an app ships no hook code.
The parity rule. Everything the operator sees in the panel, the agent can
read through a tool; everything the operator can press, the agent can do
through a tool or an argument. The panel and the tool server are two front
ends to one backend, so parity needs no second implementation: each panel
element maps to a backend route, and each route the panel uses has a tool.
A route can still tell the two apart: an agent’s tool call arrives as
agent and a panel call as panel (The backend).
Design the skill from a parity table, one row per panel element:
Panel element |
Tool or argument |
Route |
|
|---|---|---|---|
a value it shows |
the read tool, and the field it answers |
|
|
a control that writes no channel |
a tool, or an argument of one |
any |
|
a control that writes a channel |
the write tool |
|
|
Then:
One read tool answers the whole screen, in the panel’s terms: the values per element, the statuses, and why a control is disabled, in the sentence the panel shows. The agent then answers what does the panel say and why can’t I apply without guessing.
Every control is a tool or an argument. Toggles and menus become arguments (a checkbox Include neighbours is an argument
include_neighbours); buttons become tools. A gesture that only edits input — drag, nudge — needs no tool when the agent can pass the resulting values. A convenience the operator relies on is an argument, so the agent builds the same input the same way (an amplitude and a shape, not the setpoints they produce).Publish the operator’s input. What the operator has set but not yet sent is on screen too. The panel posts it to a route that writes no channel, and the read tool returns it, so the agent never has to ask what the operator is looking at. The route is the operator’s: leave it out of
agent_routes.Classify by what is written, not by the method. A route that writes no channel — compute a plan, drop it, rebuild a model — backs a
readtool even when its method isPOST; the terminal still handsPOSTroutes to the agent only on a login that arms the app. A route that writes a channel backs anapprovaltool, bound to what the operator saw (Writes and approvals).Write the skill from the table: which tool for which request, the arguments in the facility’s terms, how to read each status, what each refusal means, and the order — look, plan, show, then ask to write. Name each tool’s panel equivalent, so the agent can tell the operator where to look. Say what the agent does not get (view settings such as zoom) and why.
The scaffold’s SKILL.md is the smallest case of this: one table of tool,
panel equivalent and whether it writes, then the order of calls and what a
refusal means. Agent Skills gives the format.
Subagents#
A subagent is an agent the main agent hands a task to. It works in its own
context with its own tool list and returns an answer, so a task that reads a
lot — a search, a comparison over many records — does not fill the main
conversation. An app carries its own: list the name under agents: in
app.yml and write agents/<name>.md in the app’s directory, one file
per agent. The build installs it into every login that shows the app.
---
name: trim-history
description: Finds and summarises earlier trims of a corrector.
tools:
- mcp__corrector-trim__list_trims
- mcp__corrector-trim__read_trim
delegates:
- list_trims
- read_trim
delegation: >-
For questions about earlier trims, delegate to trim-history; do not
call {delegated_tools} yourself.
---
You answer questions about earlier trims of one corrector. ...
The frontmatter keys, required unless marked optional:
Key |
Meaning |
|---|---|
|
The agent’s name; the file name without |
|
What the agent is for; the main agent routes by it. |
|
The tools the agent may call; a tool of the app is
|
|
The note the main agent’s brief carries for this agent: when to hand it a task. |
|
Optional. Tools of the app the main agent is told to leave to this
agent; their names replace |
|
Optional, as in OSPREY’s own agent files. |
The text below the frontmatter is the agent’s instructions, copied as written.
Four keys an agent file may carry elsewhere are refused in an app:
model— the deployment sets each agent’s model (claude_code.agent_models);hooks— an app ships no hook code; it declares facts inapp.ymland OSPREY’s hooks act on them;mcpServers— an app’s tools are itstools:server;permissionMode— the login’s tier and the write switch decide.
A listed agent without its file, an agent name two apps share, and a name of one of OSPREY’s own agents each fail the build.
An app needs neither a skill nor a subagent. Use a skill when the main agent should do the task itself and needs to know how; use a subagent when the task is better done out of the main conversation; an app may carry both.
Test your app#
The app’s own tests build a deployment the way osprey build does and run
the backend against one login’s render. Installing the framework gives them
two pytest fixtures from osprey.apps.sdk.testing: synthetic_deployment
makes a deployment, rendered_tree makes one and builds it. Both take:
apps— each app’s name and its source directory;facility— thedata/facilitytree. The default,plain_tree(), is one quadrupole and one BPM;measured_tree()is two models wired for the built-in measurement kinds, for a test to extend with its own kind’s records;logins— each login and itscontrol_system.writesceiling, onetiers/file each (default:operatoratasked);profile— profile keys laid over the generatedprofile.yml, such as the app’sconfig:.
Every login runs on the simulator served in process. serve(login) gives
the app container’s environment on that login’s render; build the backend
inside it and call it with the header the terminal sends:
from pathlib import Path
from corrector_trim.server import create_app
from fastapi.testclient import TestClient
APP_DIR = Path(__file__).resolve().parents[1]
def test_state_reads_the_configured_channel(synthetic_deployment):
deployment = synthetic_deployment(
apps={"corrector-trim": APP_DIR},
profile={"apps": {"corrector-trim": {"config": {"channel": "Q1:RB"}}}},
)
served = deployment.serve("operator")
with served.environment(), TestClient(create_app()) as client:
state = client.get("/api/state", headers=served.headers()).json()
assert (state["channel"], state["target"]) == ("Q1:RB", "va")
The build behind serve is real, so what osprey build refuses fails the
test with the build’s own message. Run pytest with the app’s directory
on the import path, so the test can import the app’s package.
Dependencies#
pyproject.toml is the app’s package. The scaffold lists no dependencies:
FastAPI, uvicorn, httpx and the connectors are already in the image. Add what
your app needs under dependencies — numpy, for instance — and the
build installs it with the wheel. A package that would change a version the
framework pins is refused by osprey app check.
The panel’s files and the skill are included in the wheel by the
force-include block, so the installed package carries them. When you
delete panel/ or skills/, delete its line there too.
Manifest keys#
An app ships no hook code; it declares facts in app.yml and OSPREY’s
hooks act on them: tools.approval for a write, tools.deny_in_jobs for
a job-only refusal, tools.errors for the agent’s guidance. osprey app
check and the build refuse a hooks key, a hooks/ directory at the
app’s root and a .claude/ directory anywhere in it, each with rule
no_hooks.
Every level refuses unknown keys. Defaults in brackets.
Key |
Meaning |
|---|---|
|
The app’s name, |
|
One sentence about the app. |
|
Optional. Required by |
|
One container; the key is its service name. Exactly one of
|
|
What a |
|
The health route, polled by the terminal. |
|
The container reaches the control system. |
|
The container’s process identity names the person behind the write
to the control system (the Channel Access user), instead of the
shared |
|
A directory kept across restarts, relative to the deployment’s state zone. |
|
Host environment variable names passed into the container. |
|
A fixed port; otherwise the build assigns one. |
|
The sidebar row’s text. |
|
The sidebar row’s icon, one of the names the terminal draws (see Panels). Without it the row wears the generic one. |
|
The sentence the sidebar row’s tooltip shows under its text. |
|
The panel’s Help page: a path under the deployment’s docs root
(no |
|
The container that serves the panel. |
|
The route the panel opens at. |
|
The write routes demand a token the terminal adds on an armed login. |
|
Seconds a proxied request may take; for a route that performs a long action, such as a write of many setpoints with read-back. |
|
|
|
The panel works for the alias login of a single-user deployment, which has no roster. |
|
The Python module run as the tool server. |
|
Tools that only read. |
|
Write tools, each with its approval entry (Writes and approvals). |
|
No dispatch job runs any of the app’s tools. |
|
|
|
The sentences the agent sees for a backend that does not answer, and for a refused call. |
|
The name the containers’ spool and state directories file under; refused on an app with no container. |
|
Files fetched into the app at build: |
|
The skills the app carries, each |
|
The subagents the app carries, each |
The command reference is osprey app; the SDK’s names
are listed in osprey.apps.sdk.