Gateway owner socket
Each request is tagged by type (snake_case) and each answer by type too. A request that changes something is owner-local: the gateway refuses it owner_local_required unless it arrives on the owner-local control endpoint.
Living doc, checked against the code 2026-11-14
admin.v6 — the Admin owner socket: one request, one answer, every request and projection
- Status: accepted (2026-11-08). The wire it describes is live as Admin protocol 6 (
ADMIN_PROTOCOL_VERSION). - Stability:
owner(docs/contracts/api-surfaces.toml, surfaceadmin). This is the operator’s own control plane and may change in any release, with no promise to a third party. A third party uses frontend.v5, the agent connector, hooks or the CLIs instead. - Scope: Vulpine Gateway.app (
apps/admin-shadow, throughcrates/admin_core),vulpine-glyphctland the headless dispatcher, asking the Voice Gateway on the same host, or on the gateway host through the Admin relay. - Schema:
admin.v6.schema.json, generated fromAdminRequestandAdminResponseincrates/protocol, is the field-level truth. This file is the transport, the access rules and the index of every request and answer. Requests are#/definitions/AdminRequestand answers are#/definitions/AdminResponse. Each card’sopenum and projection is a definition under its own Rust name (AdminReachOp,AdminPacksAnswer, …).
Transport
| what | rule |
|---|---|
| socket | a Unix socket at <state>/admin/<socket_name> (default admin.sock, under the vulpine state root; crates/admin_markers/src/socket.rs). Off by default: [admin] enabled. |
| authority | the Admin directory is mode 0700, and two 0600 marker files sit beside the socket: .fox9-admin-owner (exactly fox9-admin-socket-v1 and a newline) and .fox9-admin-endpoint (the socket’s basename). The gateway refuses to start the endpoint when either is missing or wrong, and never creates them (admin, “Authority and transport”). |
| request | one AdminRequest as JSON plus a newline, then the client closes its write half. |
| answer | one AdminResponse as JSON, read to end of stream, at most 256 KiB (MAX_ADMIN_RESPONSE_BYTES), within 30 s (ADMIN_IO_TIMEOUT). A client checks it with admin_markers::bounds::validate_admin_response before it shows anything. |
| version | ADMIN_PROTOCOL_VERSION = 6, repeated as protocol_version inside each projection and on error. |
| other routes | the Admin relay carries these frames from another machine to the gateway host over ssh or vulpine/relay/1 (internal; crates/vulpine_relay); the headless dispatcher (crates/admin_core/src/headless.rs) takes one JSON line per request and needs a token off loopback. Both are owner tools. |
Each request is tagged by type (snake_case) and each answer by type too. A request that changes something is
owner-local: the gateway refuses it owner_local_required unless it arrives on the owner-local control endpoint.
Some write requests also sit behind config switches ([admin] config_writes, [admin] controls = "all",
[packs] enabled), each refused by name when off.
Requests (AdminRequest)
Reads: the gateway and its sessions.
type |
what | answer |
|---|---|---|
get_snapshot |
the whole Admin snapshot | snapshot |
get_health |
adapter health and topology (owner-local) | health |
get_performance |
turn and leg latencies | performance |
get_events |
the Admin event timeline | events |
get_presentation |
live sessions, personas, voices | presentation |
get_presence |
the embodiment presence | presence |
get_speech_text |
the written and spoken text per render | speech_text |
get_decision_shadow |
the decision shadow’s verdict counts | decision_shadow |
get_pi_spend |
Brain spend per day, model and session | pi_spend |
get_vulpine_report |
vulpine’s report on itself, one topic | vulpine_report |
get_setup_census |
each connector, grant and switch with its state and next step | setup_census |
get_direct_verbs |
the closed gateway verbs | direct_verbs |
get_watches |
open and settled watches | watches |
Reads: the house, the fleet and the tools.
type |
what | answer |
|---|---|---|
get_home |
home subjects’ latest state | home |
get_home_actions |
the home-action receipts | home_actions |
get_room_speakers |
the room-speaker route’s outcomes | room_speakers |
get_announcements |
the announcement governor | announcements |
get_announcement_frame |
the camera frame behind one announcement | announcement_frame |
get_camera_frames |
the latest camera frames, names and ages only | camera_frames |
get_calendar |
the operator’s calendar for 1 to 14 days | calendar |
get_fleet |
fleet hosts, ssh sessions, herdr agents | fleet |
get_approvals |
the approval queue and learned trust | approvals |
get_dispatch |
herdr task reports | dispatch |
get_pipelines |
herdr pipelines | pipelines |
get_tool_receipts |
Brain tool receipts and counters | tool_receipts |
get_tool_catalog |
every Brain tool and its loadouts | tool_catalog |
get_tool_toggles |
every loadout’s tool states | tool_toggles |
get_mcp_catalog |
MCP servers and their tools | mcp_catalog |
get_catalog |
the Catalog index and its validation | catalog |
get_hardpoints |
the open hardpoint slots and their binds | hardpoints |
get_hook_consumers |
the Observe hook consumers | hook_consumers |
get_frontier_agents |
the frontier agents at the agent door | frontier_agents |
get_sounds |
sound rules, proposals and classes | sounds |
get_packs |
the Packs rows, index and jobs | packs |
get_pack_receipts |
pack receipts, newest first | packs |
get_memo_target |
the admitted target for a memo | memo_target |
Writes and actions (owner-local).
type |
what | answer |
|---|---|---|
plan_config_mutation |
plan a config change against expected_revision |
mutation_plan |
apply_config_mutation |
apply a plan to the Admin config overlay (ADR 0065) | config_applied |
set_presence_room |
the operator says where they are | presence |
home_act |
one verb on one home subject | home_action |
write_selection |
replace the selection through the screen agent | selection_write |
mic_recalibrate |
one bounded mic recalibration step | mic_recalibration |
frontend_control |
run a frontend control in the background | frontend_control_ack |
start_background_work |
queue a memo turn for an admitted owner | background_work_queued |
mark_agent_presence_seen |
advance the fleet agents’ seen watermark | fleet |
stt_fault_inject |
make one session’s recognizer fail once (QA) | stt_fault_injected |
set_tool_toggle |
set one tool’s state in one loadout | tool_toggles |
cancel_watch |
cancel one open watch | watches |
save_sound_rule, delete_sound_rule, undo_sound_action |
edit sound rules, undo a rule’s action | sounds |
set_hook_consumer |
switch one hook consumer on or off | hook_consumers |
set_notify_mute |
mute every notification | notify_mute |
probe_decision |
ask the decision entries one typed line | decision_probe |
install_herdr_core |
put the pinned herdr-core on a fleet host | herdr_core_install |
roll_notice |
a roll is about to swap the gateway | frontend_control_ack |
Card requests with an op. Each takes an inner enum tagged op (the stage of the ops is tagged stage):
type |
its op enum and words |
answer |
|---|---|---|
sound_inbox |
AdminSoundInboxOp: list, label, delete, play, capture_now, set_label_class, train, rollback |
sound_inbox, sound_clip_audio |
turn_outcomes |
AdminTurnOutcomesOp: list, false_fire, missed_address |
turn_outcomes |
wake_inbox |
AdminWakeInboxOp: list, label, play |
wake_inbox, wake_clip_audio |
label_queue |
AdminLabelQueueOp: list, answer, play |
label_queue, label_clip_audio |
reach |
AdminReachOp: list, pair, revoke |
reach |
frontier_agents_op |
AdminFrontierAgentsOp: list, revoke, answer |
frontier_agents |
packs_op |
AdminPacksOp: refresh, plan, apply, cancel |
packs |
gateway_op, brain_op, supervision_op, hardpoint_op |
a restart, reconnect, retire or switch, each with an AdminOpStage (plan, then apply) |
op |
satellite_op |
a satellite’s Mute, Unmute, Off or On by its id (the room it declared; satellite-controls.v1), with an AdminOpStage |
op |
Answers (AdminResponse)
Every request above names its answer. The answers that no table names yet are error and the rest of the
read-only projections:
type |
what |
|---|---|
snapshot, health, performance, events, presentation, presence |
the core projections |
home, home_actions, home_action, room_speakers, announcements, announcement_frame, camera_frames, calendar |
the house |
fleet, approvals, dispatch, pipelines |
the fleet and herdr |
speech_text, decision_shadow, decision_probe, pi_spend, vulpine_report, setup_census, direct_verbs, watches |
the gateway’s own reports |
tool_receipts, tool_catalog, tool_toggles, mcp_catalog, catalog, hardpoints, hook_consumers, frontier_agents |
tools and extensions |
sounds, sound_inbox, sound_clip_audio, turn_outcomes, wake_inbox, wake_clip_audio, label_queue, label_clip_audio |
the cards that label audio; a clip’s audio is played in memory, never written by the Admin |
mutation_plan, config_applied, selection_write, mic_recalibration, frontend_control_ack, notify_mute, memo_target, background_work_queued, stt_fault_injected, herdr_core_install, reach |
receipts of a write |
op |
a gateway, brain, supervision or hardpoint op’s plan, receipt or refusal |
packs |
every packs answer, its inner AdminPacksAnswer tagged kind: view, plan, job, receipts, unavailable, refused |
error |
code, message, protocol_version, optional request_id |
Errors
error {code, message, protocol_version, request_id?}. code is a closed snake_case word, for example
owner_local_required, config_writes_off and stale_revision. A request the gateway cannot decode, including an
unknown type, gets invalid_request, never silence. The gateway screens every text field of an answer before it
leaves (the sensitive-text gate and the byte bound; admin).
Compatibility
- Owner-only. The Admin and the gateway belong to the same operator and usually roll together. There is no deprecation window.
- An older Admin reads a newer gateway. Enums the panels read keep a
#[serde(other)]unknownarm where it is safe.admin_markers’ tolerant decode reads a reply row by row when it does not decode whole, naming each row left out (admin, “An Admin older than its gateway”). - Breaking. A change an older Admin cannot read moves
ADMIN_PROTOCOL_VERSION, writesadmin.v7.mdandadmin.v7.schema.json, and retires this file to the record.
See also
- JSON Schemas: this wire’s generated schema.
- frontend.v5: the public frontend wire.
- admin: the Admin’s guide, its panels and its mutation boundary.