---
title: "Vulpine Gateway.app"
description: "The GPUI Admin (ADR 0060), installed as Vulpine Gateway.app: the Admin's sections in one GPUI window, reading through admin_core in process, the ported sections, how a panel lane adds a panel (one module, two lines of the registry, its own baseline folder), and how to install and open it."
type: "living"
source: "apps/admin-shadow/README.md"
verified: "2026-11-14"
group: "Frontends"
---

> **Living doc**, checked against the code 2026-11-14

Vulpine Gateway.app is the gateway's host app. Its window, the Gateway window (the Admin in the code), draws every
Admin section in one GPUI window, from admin_core in process. Its name, bundle id `com.voidfab.vulpine.gateway`,
executable `vulpine-gateway` and brand icon are all in `bundle.json`. The crate and its binary keep
the name `admin-shadow`. What each page shows is [the Gateway window](/docs/frontends/admin).


## What it is

- **The host app.** `just apps::admin-install [host]` installs it as `Vulpine Gateway.app` in the host user's
  `~/Applications` (the default gateway host alias; `local` installs on this Mac). It builds the GPUI release through
  `scripts/release/gateway_bundle.py admin-app` (the Info.plist and the build record from `bundle.json` and the
  stamp, then a scan for private text that refuses the install on a finding), signs it with the operator's signing
  identity (hardened runtime), verifies it on the host and swaps it in, keeping the old bundle as
  `Vulpine Gateway.app.previous`. There is no Sparkle and no notarization. The window title and the menu say Vulpine
  Gateway; the sidebar says VULPINE GATEWAY · ADMIN. `just apps::gateway-release-bundle` builds a release bundle that
  also carries the gateway and its core helpers, so a new Mac needs no checkout.
- **The sidebar** holds eight groups and 27 pages (`GROUPS` in `src/sections.rs`). A page can carry tabs: Configuration
  holds Connectivity, Models, Transports, Sessions and Audio, Packs holds the Catalog, Pipelines holds Dispatch, and
  Decision holds the Label queue. Every page draws its panel.
- **The banners**: "Some Gateway Admin reads failed." or "Gateway Admin unavailable." with the failed reads named, the
  gateway line (this Mac, or the gateway host through the Admin relay), and a notice of the reply fields that could
  not be read, filtered per tab.
- **Reads.** admin_core runs in this process behind its own dispatcher. The read gate (`data::admit`) lets through only
  a command that `admin_core::COMMANDS` lists with `writes: false`. Reads run one at a time, 150 ms apart, a cycle every
  4 s (6 s through the Admin relay), so the app holds at most one of the gateway's 8 Admin connections
  (`MAX_ADMIN_CONNECTIONS`). A read that
  takes an argument (Fleet's Inspect, Approvals' diff) runs once on a press (`src/arg_reads.rs`).
- **Writes ask first.** Every write control goes through one write path (`src/writes.rs`): it shows the plan in words
  (native-kit's `confirm` card), Confirm sends it, and the gateway's answer is the receipt. One write runs at a time,
  and a fixture window sends nothing. The write controls: Cancel a watch, Advance, Mark seen / Mark all seen, the Tool
  toggles, Apply and read back, the Label queue (answered with its keys, no confirm per answer), Close…, the Usage
  switches, Recent turns' labels, the notify mute, the Wake and Sound inboxes, Sounds' Approve / Dismiss / Delete /
  Undo and its Add rule form, the Frontier agents and Hook consumers cards, Install herdr-core (the gateway's plan, a
  second confirm for the download, then a 3 s poll) and an announcement's "show frame". The three Play buttons fetch a
  clip's parts on a press and play them from memory (`src/clips.rs`). The Controls page (restart, the frontends, the
  mic, the loadout, the editable config) goes through the same path; its riskier rows stay grayed until
  `VULPINE_ADMIN_CONTROLS=all` turns them on (`src/panels/controls.rs`).
- **The remembered section.** With no `--section`, a live window opens the section it last opened (`src/remember.rs`:
  one section id in a file named `section` in `~/Library/Application Support/com.voidfab.vulpine.gateway`). At its
  first launch from the installed bundle it moves the host's state from its earlier bundle ids once
  (`crates/vulpine_bundle_move`).
- **Decision.** The Decision section probes a settled line against a non-live lab copy from this Mac (decidectl), or
  with `ProbeDecision` to the gateway when the gateway host is picked. The lab copy is `VULPINE_DECISION_LAB_URL`, else the
  first line of `decision-lab-url` in the same Application Support folder, else `http://127.0.0.1:18873/v1/systemone`
  (an ssh tunnel to a non-live copy's loopback port).

```text
admin-shadow [--fixture <admin-sections.v1.json>] [--section <id>] [--size WxH] [--exit-after <s>]
```

`--fixture benchmarks/fixtures/admin-sections.v1.json` answers every read from the fixture and dials nothing.



## Install, open and roll back

- Install: `just apps::admin-install [host]` (default the gateway host alias; `local` for this Mac; `--dry-run` writes the stamp and
  the Info.plist only). This Mac builds and the host installs.
- Open, on the host from its GUI session: `open -a "Vulpine Gateway"`. With no gateway: `open -a "Vulpine Gateway"
  --args --fixture "$PWD/benchmarks/fixtures/admin-sections.v1.json"`.
- Roll back on a host: `cd ~/Applications && rm -rf "Vulpine Gateway.app" && mv "Vulpine Gateway.app.previous"
  "Vulpine Gateway.app"`, then quit and reopen it.

