Event Dispatch#
How to turn external events (a webhook call, a fixed interval or a time of day, an EPICS channel crossing a threshold) into headless OSPREY agent runs.
What You’ll Learn
What the event dispatcher and dispatch worker do
How to bring the pipeline up and fire your first trigger
How to fire a trigger from a web-terminal session, and who the job runs as
How to author your own triggers in
triggers.ymlWhich trigger sources ship, and what each one’s
source_configtakesHow the two bearer tokens guard inbound and internal traffic
Prerequisites: A project built from the demo preset
(or any profile with a dispatch: block). Docker/Podman only for the
container path.
Overview#
Event dispatch lets an external event start an agent run with no human at a keyboard. It is built from two services:
Event dispatcher (
python -m osprey.dispatch, port10010) — accepts authenticated webhookPOSTs, interval and clock-time ticks and EPICS channel crossings. It matches each to a trigger, applies the trigger’s tool allowlist and error policy, and forwards the run to a worker. It also serves the monitoring dashboard.Dispatch worker (
python -m osprey.mcp_server.dispatch_worker, port10011) — runs the headless agent session and streams progress back.
Both numbers are the deployment’s port layout at its default base; move
deployment.port_base and they move with it. See Ports.
The demo preset ships this enabled, wired to four
control-system-free tutorial triggers so you can exercise the full pipeline
with a single curl. osprey build writes triggers.yml, both service
compose templates, and the services.{event_dispatcher,dispatch_worker}
config into your project, and appends both to deployed_services.
Bring It Up#
Both services are registered in deployed_services, so they come up with the
rest of the stack. osprey up auto-generates both bearer tokens into
the profile’s .env when they are unset, then derives the project’s .env
from it:
osprey up # add --dev to bake in a local osprey checkout
The first build is slow: both images install Node and the agent CLI the worker runs on.
Image build & overrides
The two services use two different images, both built locally on first
osprey up:
the dispatcher gets its own small image (
<project>-dispatch:local, fromservices/event_dispatcher/Dockerfile);the worker runs the full project image (
<project>:local— the same image The Project Image describes, with your profile’s artifacts anddata/baked in), so the agent it launches sees the real project.
Pass --dev to install your local osprey checkout (incl. unreleased
code) via a wheel; otherwise the images install osprey-framework from
PyPI. To use prebuilt/published images instead of building, set the
override env vars — note they take different kinds of image: the worker
override must be a project-style image containing /app/<project>, not
a dispatch image:
OSPREY_DISPATCH_IMAGE=my-registry/osprey-dispatch:dev \
OSPREY_WORKER_IMAGE=my-registry/my-project:dev \
osprey up
Inside the compose network the worker is reachable as
dispatch-worker-1:10011 — the default dispatch_target in
triggers.yml. See Container Deployment for the deploy mechanics.
Run without containers (dev)
Both services are plain Python entrypoints, so you can run them straight from
your venv — handy for development. First repoint the worker URL in
triggers.yml (the Docker hostname does not resolve on the host):
dispatcher:
dispatch_target: http://localhost:10011
Generate the two bearer tokens once (the containerized path does this for you; here you set them by hand) and export them so both shells share them:
export EVENT_DISPATCHER_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export DISPATCH_WORKER_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
Start the worker (it reads config.yml to inject the same provider auth
the web server uses):
OSPREY_PROJECT_DIR="$PWD" \
DISPATCH_WORKER_TOKEN="$DISPATCH_WORKER_TOKEN" DISPATCH_WORKER_PORT=10011 \
uv run python -m osprey.mcp_server.dispatch_worker
Start the dispatcher in a second shell (re-export the same two tokens there first):
TRIGGERS_YML="$PWD/triggers.yml" \
EVENT_DISPATCHER_TOKEN="$EVENT_DISPATCHER_TOKEN" DISPATCH_WORKER_TOKEN="$DISPATCH_WORKER_TOKEN" \
FASTMCP_TRANSPORT=http FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=10010 \
uv run python -m osprey.dispatch
Fire a Trigger#
The bundled tutorial_triggers.yml defines four demos, each isolating one
concept:
hello-dispatch— anatomy of a trigger and a first successful round-trip (zero tools, empty payload).triage-event— the webhook JSON body becomes the agent’s context; it reasons about the event with no tools.save-report— tool use across a short multi-turn loop, persisting a status report as an artifact in the worker workspace.denied-tool-demo— requestsWebFetchto prove the worker’s server-side denylist rejects it regardless of the trigger’s allowlist.
First read the generated token back from .env so the
$EVENT_DISPATCHER_TOKEN reference resolves:
export $(grep -E '^EVENT_DISPATCHER_TOKEN=' .env | xargs)
Then POST to a trigger’s webhook (the JSON body is passed to the agent as
untrusted payload):
curl -X POST http://localhost:10010/webhook/hello-dispatch \
-H "Authorization: Bearer $EVENT_DISPATCHER_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
To see a payload reach the agent, fire triage-event with a realistic body:
curl -X POST http://localhost:10010/webhook/triage-event \
-H "Authorization: Bearer $EVENT_DISPATCHER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"signal":"demo:vacuum:pressure","value":4.2,"threshold":3.0,"severity":"warning"}'
Watch runs stream live on the dashboard at http://localhost:10010/dashboard, or
in the EVENTS tab of osprey web.
The EVENTS Panel#
Projects built from the demo preset surface this dashboard as
an EVENTS tab inside the web terminal, so osprey web exposes it without a
separate browser window. The tab health-gates itself. While the dispatcher is
down, the tab is disabled with an offline indicator rather than showing a
broken frame. It turns live once the dispatcher answers /health.
The panel points at http://localhost:<dispatcher_port>. That address works
out of the box in two cases:
the host-run flow in Bring It Up;
every tier built beside the deployment. Per-user containers share the host’s network, so the dispatcher answers on their loopback too. The build copies this entry from the deployment’s render into each tier (Build Profiles).
Auto-derived URL#
You do not have to set web.panels.events.url by hand. Whenever a profile
lists the events panel and declares a dispatch: block, the build
derives the whole panel entry from dispatch.dispatcher_port:
web.panels.events.url: http://localhost:<dispatcher_port> # bare host
web.panels.events.path: /dashboard # route
web.panels.events.label: Events # tab title
web.panels.events.health_endpoint: /health # what the tab health-gates on
The url is the bare dispatcher host and path carries the /dashboard
route. The web terminal composes the backend target as url + path, so
baking /dashboard into url would double-prefix sub-routes. Keep them
split.
The build leaves untouched any of these keys a profile already pins, and an
explicit web.panels.events.url always wins. Pin it on the hosting
profile when the web terminals cannot reach the dispatcher on localhost.
Every tier follows it, and a tier that pins a different one is refused.
Firing a Trigger from a Session#
A deployment that declares the EVENTS panel also hands the agent in each web
terminal a small event_dispatcher MCP server. With it, you can start a job
from the session you are already working in. Three of its tools read and
answer straight away — list_triggers, trigger_status and
trigger_history. The times they report are in the facility zone. The
fourth, manual_fire, starts a job and asks first.
Ask for it in plain language — “fire the save-report trigger” — and an approval prompt appears. It names the trigger the fire would start, and the payload where the call carries one. That way the name to check is on the prompt rather than in the agent’s message above it.
The job runs as you#
Approve, and the run is attributed to your account. The terminal’s proxy stamps your name onto the call, and the worker starts the agent under it. Every control-system write that job makes then follows your tier and your write switch. Turn the machine off and the job you fired refuses its next write, with the refusal you would have seen in the terminal. The worker reads your tier from the login→tier map the build renders into its config (Who May Write). The name comes from the session the call left, never from a tool argument or a header the agent can set. So there is no way to fire on someone else’s behalf.
The control system sees the job’s writes under the worker’s own service name,
osprey-dispatch-<i> for worker i, not under yours: one worker runs jobs
for everyone. Your name goes into the audit trail instead, as owner= on
the job’s write records beside the worker name. That is how a line in the
gateway’s put-log is joined back to you. See Who the control system saw.
A job that a trigger source started carries no name: an interval or
clock-time tick, a channel crossing or an inbound webhook. Neither does a job
whose account name the dispatcher cannot read. A name that is not a plain
account spelling is refused, and the only trace is a warning in the
dispatcher’s own log. A job with no name writes nothing: no switch covers
it, so each write is refused owner_unscheduled. This is a breaking change
from earlier releases, where such a job wrote at the deployment’s own setting.
There is no route back yet: a schedule that names the login whose switch it
follows is a later dispatch feature. Keep scheduled jobs to reads and reports,
or fire the write from a terminal.
Where the tools work#
The entry is rendered wherever the profile declares the EVENTS panel — which
includes a bare osprey chat session and the dispatch worker’s own runs.
Neither of those has a terminal serving the panel route, so the server cannot
connect and reports itself failed or needs-auth while the session
starts. That is inert: the session comes up as usual, without the dispatcher
tools. The dispatcher tools are reachable from a web-terminal session only.
A job also cannot fire jobs. A trigger whose allowed_tools names any
mcp__event_dispatcher__ tool is refused when the triggers file loads, with
an error naming both the trigger and the tool. The worker’s server-side
denylist also blocks manual_fire, whatever a dispatch request asks for.
A shell can still reach the route#
The panel token is meant for the agent’s MCP tools and hooks. Claude Code
starts every Bash and Monitor command with the token removed from its
environment. The agent process itself keeps it, though, and a shell running as
the same user can read it from that process (/proc/$PPID/environ on Linux).
So a tier whose file lifts the Bash deny can fire a job from a shell
command with no approval prompt. Lifting that deny is a build failure unless
the same file also declares its own PreToolUse gate covering the shell.
What that skips is the prompt, not the rest. Such a job still carries your name
from the proxy, still meets your chip at every write, and still runs under the
worker’s denylist. Code
running in a sandbox holds neither the panel token nor the terminal’s port, so
it cannot make this call.
Reaching the Machine#
A trigger’s source: decides what wakes it. webhook and cron need
nothing from the network. epics_ca monitors channels and does. On a site
where those channels live behind a gateway, the dispatcher has to be told where
the gateway is. Both halves of the pair take that from the deployment’s
env chain, through one profile key:
dispatch:
triggers: my_triggers.yml
env: [EPICS_CA_ADDR_LIST, EPICS_CA_NAME_SERVERS]
Each name is passed through to both containers as NAME: ${NAME}, so the
values live in .env / .env.shared and rotate with an edit and a restart.
The worker gets the same list as the dispatcher: a run acting on what a trigger
saw has to be able to see it too. The dispatcher’s epics_ca triggers watch
through an EPICS connector that takes its gateway from these variables alone,
not from the gateways under control_system.
The worker’s own reach is a separate question, and it is a network one. A dispatched job runs the same OSPREY agent a web terminal runs, so it reaches the control system and the plan queue at whatever addresses your deployment was written with. When those are this machine’s own — a control system, a Bluesky bridge or an archiver running beside the stack — the pair belongs on the host’s network:
dispatch:
network: host
triggers: my_triggers.yml
Without it a job runs, the agent answers, and every write and every queue call
is refused on connect: inside a container on the compose network, localhost
is the container. See Network attachment: bridge or host for what that
setting changes and what has to move with it.
Authentication#
Two bearer tokens guard the stack. osprey up auto-generates a strong
random value for each when it is unset (and logs where it wrote it), so a
containerized deploy needs no token editing. A generated value is written into
the profile’s .env and derived from there into the project’s, so a
rebuild comes up on the same token. To pick your own values, set them in the
profile’s .env and rebuild:
EVENT_DISPATCHER_TOKEN— guards inbound webhook and write endpoints, and the MCP transport at/mcpthatmanual_firearrives on. Send it asAuthorization: Bearer <token>.DISPATCH_WORKER_TOKEN— guards the dispatcher → worker calls. The worker takes it out of its environment into memory when it starts, so the runs it launches do not inherit it.
Anything that drives the pipeline from outside holds both. A chat bridge, for instance, fires its trigger at the dispatcher with
EVENT_DISPATCHER_TOKEN. It then collects the finished answer and its files
from the worker with DISPATCH_WORKER_TOKEN. A bridge that has only one of
them stalls partway through every question.
EVENT_DISPATCHER_TOKEN is an admin credential. One value covers the
webhook, the /mcp transport and every dashboard write: re-firing a
trigger, cancelling a run, clearing the run history, and enabling or disabling
a trigger. There is no narrower per-trigger token. Hand it only to the web
terminal and to the bridges that fire triggers.
The dispatcher records who asked, but it does not check it. A fire or re-fire
made from the web terminal carries your account name, added by the terminal’s
panel proxy. The dispatcher stores it as owner on the trigger’s history
entry and on the run record. Cancelling a run, clearing the history and
enabling or disabling a trigger log the same name. A webhook, a cron
trigger and a chat-bridge fire name nobody and are recorded without an owner.
The recorded owner is attribution, never authorization. The token decides what
a request may do, and anyone holding it can call the dispatcher’s port directly
under any account name or none.
How the tokens work
The dispatcher fails closed if EVENT_DISPATCHER_TOKEN is unset — it
never accepts an empty token. The webhook and dashboard routes answer HTTP
503 while it is unset, which is how an unconfigured dispatcher announces
itself, and 401 for anything else, a missing header included. The MCP
transport at
/mcp answers 401 in both cases: a bearer check there has one way to
refuse, so it cannot draw the distinction the routes draw. The dashboard
read endpoints (run
feed, trigger list, state, SSE stream) are gated by the same token: the
in-terminal EVENTS tab injects it server-side so the browser never holds it,
while the standalone dashboard receives it via a one-time URL-fragment
handoff.
To call the API by hand, read the generated token back from .env (as in
Fire a Trigger above):
export $(grep -E '^EVENT_DISPATCHER_TOKEN=' .env | xargs)
See also
- Container Deployment
Container deployment mechanics for all Osprey services.
- CLI Reference
Full
osprey buildand lifecycle-verb reference.