Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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, surface admin). 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, through crates/admin_core), vulpine-glyphctl and 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 from AdminRequest and AdminResponse in crates/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/AdminRequest and answers are #/definitions/AdminResponse. Each card’s op enum 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)] unknown arm 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, writes admin.v7.md and admin.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.

Was this page helpful?