---
title: "Gateway owner socket"
description: "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."
type: "living"
source: "docs/contracts/admin.v6.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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](/docs/contracts/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](/docs/frontends/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](/docs/contracts/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](/docs/frontends/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](/docs/frontends/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](/docs/contracts/json-schemas): this wire's generated schema.
- [frontend.v5](/docs/contracts/frontend.v5): the public frontend wire.
- [admin](/docs/frontends/admin): the Admin's guide, its panels and its mutation boundary.
