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

Vulpine.app, the desktop app

Vulpine.app is the desktop app on the Mac (bundle id com.voidfab.vulpine, productName in src-tauri/tauri.conf.json). Glyph is its look: an ambient overlay that sits on screen beside your work.

Living doc, checked against the code 2026-10-06

On this page “Glyph” means the app as it draws in that look; menus and logs still say Glyph. The app runs as a Tauri shell whose windows are moving to GPUI one surface at a time. It connects to the gateway and draws a swappable body (the chassis, ADR 0036) around a swappable face, the Visual Theme: Orb, Cast (textmode.js engines), LED (the scanner face) or SVG. The frontends overview lists the other ways to talk to Vulpine.

Architecture

Glyph Tauri shell
  -> @voidfab/vulpine-voice-client
      -> vulpine-voice-gateway WebSocket

The gateway owns STT, TTS, turn authority and the brain. Glyph owns shell integration, microphone capture, audio playback and visuals. There is no local STT, TTS or LLM path: run vulpine-voice-gateway before you start Glyph.

First launch and the control socket

Give a newly installed Glyph its first launch from Finder. If macOS asks, click Open Anyway in System Settings → Privacy & Security. A first launch from ssh or launchctl kickstart is refused (OS_REASON_CODESIGNING), because the signing identity is not notarized. After one Finder launch, launchd and ssh launches of the same bundle work.

Glyph and vulpine-glyphctl talk over glyph.sock, under $XDG_RUNTIME_DIR, else under $TMPDIR (socket_path in src-tauri/src/ipc.rs). The socket’s directory must be owner-only (0700), or Glyph refuses to start. Once the socket is bound, Glyph writes its path to a pointer, ~/Library/Application Support/com.voidfab.vulpine/glyph.sock.path (0600). vulpine-glyphctl tries --socket <path> or $VULPINE_GLYPH_SOCKET first (that path alone), then the pointer, then the pointer under each earlier bundle id’s folder (crates/vulpine_bundle_move/src/legacy.rs), then this shell’s own path. It uses the first that answers, and a stale pointer falls through (src-tauri/src/ctl_socket.rs). So a vulpine-glyphctl in Terminal reaches a Glyph opened from the Dock, whatever TMPDIR the terminal exports.

If vulpine-glyphctl still says connection refused, find the socket with lsof -U -c glyph and run vulpine-glyphctl with the same directory, for example TMPDIR="$(getconf DARWIN_USER_TEMP_DIR)" vulpine-glyphctl status.

A gateway on another Mac. Operations → Connection & privacy → Gateway on another Mac runs the relay (scripts/glyph-gateway-relay) as a login agent. Name the gateway Mac’s ssh alias; it is written to [hosts] mini in ~/.config/vulpine/fox9.toml. The relay is an ordinary ssh command hop, not ssh -L. It needs tools/gateway/glyph_gateway_remote_proxy.py installed on the gateway host as ~/.cache/fox9/runtime-relays/gateway-remote-proxy.py. The card shows the route, the relay’s state, its last hop error and the loadout the session bound.

Configuration

Glyph reads config.toml from $XDG_CONFIG_HOME/glyph, else ~/.config/glyph (config_dir in src-tauri/src/config.rs), and writes defaults on first run.

  • [glyph] chassis is the launch body until a live switch is saved. After that Glyph launches with the last body picked; an unknown id falls back to classic. A fresh install writes chassis = "halo" and shows the Cast face in its Seal variant until a face is picked.
  • [glyph] labs (default false) is the one Labs switch. Off, the Labs orb styles (Bricks and Voxel) are not offered in Look → Orb style, a pick of one is refused, and a remembered one draws Classic.
  • Gateway settings live under [vulpine]. A file that says [foxline] is still read, with one launch line on stderr naming the new table; [vulpine] wins when a file has both.
[vulpine]
url = "ws://127.0.0.1:8780"
agent = "operator"
persona = ""
workspace = "catalog/agents/operator"
loadout = "default"
# ADR 0021 client speech-hint floor as the voice-client bargeInMinimumLevel
# (0, 1]; a mic frame during assistant playback corroborates a barge when its
# residual RMS clears level / 14. 0.18 = -37.8 dBFS (a laptop's built-in mic).
# A desk interface and microphone measured a conversational overlay at -43 dBFS
# and echo-only frames under -45 dBFS (ADR 0026 Pass 2), so it runs 0.07 (-46 dBFS).
barge_in_min_level = 0.18

workspace is the brain’s working directory on the gateway host, not a path on the Glyph’s machine. A Mac that talks to a gateway on another Mac names the absolute directory on the gateway host, for example <checkout>/catalog/agents/operator. An empty workspace becomes catalog/agents/<agent>, and start_session fails if that relative path does not exist on the gateway host.

Glyph sends no project root, cwd or Git path. When the loadout enables owned attention, the gateway resolves the project root from the agent workspace and refuses the session if that repository is unsafe or unavailable.

Hold-to-talk on the Globe key

global_shortcuts.hold_to_talk is the dictation key: hold it, speak, let go. It is absent by default. A chord table ([global_shortcuts.hold_to_talk] modifiers = […] key = "D") uses the Carbon hotkey path. The Globe (fn) key has no scancode there, so hold_to_talk = "Globe" uses a small listen-only helper, globectl:

[global_shortcuts]            # TOML allows this header after the sub-tables
hold_to_talk = "Globe"
# globe_helper = "~/.local/bin/globectl"   # default: beside the Glyph binary, then ~/.local/bin
[global_shortcuts.hold_to_talk_fallback]  # optional: used only when the Globe key cannot run
modifiers = ["CommandOrControl", "Alt"]
key = "D"

Glyph runs globectl (tools/globe/globectl.swift) as a supervised child. If the helper or its grant is missing, Glyph logs why, registers the fallback chord if one is set, and still launches.

The helper ships inside Vulpine.app at Vulpine.app/Contents/MacOS/globectl, the first place Glyph looks, signed with the app’s identity. A bundled Glyph needs no globe_helper line. For glyph-dev, build it with just build-globectl or point globe_helper at a copy.

One-time setup on each Mac:

  1. System Settings → Keyboard → “Press 🌐 key” → Do Nothing. The helper only listens and cannot swallow the key, so any other setting also opens the emoji picker or switches input source.
  2. System Settings → Privacy & Security → Input Monitoring → enable Vulpine. macOS judges the responsible process, which is the app when it spawns the helper. Until the grant is on, the helper prints no_input_monitoring and retries every 5 s. After you install a new bundle, check this row again: a re-signed app can need its row toggled off and on.
  3. tools/globe/globectl --probe reports both: input_monitoring (granted / denied) and fn_usage (do_nothing is the one wanted; unset is the system default, not Do Nothing).

Two gestures sit on top of the hold:

  • Double-tap for hands-free. Two Globe taps whose presses are inside 400 ms (each tap under 300 ms, no other key during it) open a dictation that keeps listening with the key up. It ends on the next tap, on Esc, or after 2.5 s with no new words in the partials (6 s to start talking). The first tap is an empty hold the gateway drops.
  • Esc discards. Esc during a hold or a hands-free dictation ends it and nothing is typed. The tap only listens, so the Esc also reaches the focused app.

Both keys wait for the microphone to settle. A microphone plugged in, unplugged or made the default sends a burst of Core Audio notifications. A press inside that burst waits for it to end, at most 1.5 s, before it opens the mic.

Where the words land, and review mode

Glyph types a held dictation (dictation.v1 source: hold). It asks the screen agent over its socket (~/.local/state/vulpine/screen/screen.sock; screen_agent_socket overrides) to type the words into the app that had the focus at key-down. It relays the agent’s insert proof, which “scratch that” erases by.

The target is pinned. Every write carries the key-down app’s pid and bundle id, and the screen agent refuses to type if the front app changed, so words never land in another app. A refusal shows on the chip as APP CHANGED — NOT TYPED (NOT TYPED — <reason> otherwise), with no Scratch that beside it.

Trailing capture (hold_to_talk_trailing_capture, default true). A key-up while you are still speaking keeps the microphone open until 250 ms of quiet, never past 1.5 s. false ends the capture at key-up. The Trailing capture switch sets the key (below).

hold_to_talk_literal = false turns on review mode (default true: type at release). Nothing is typed at release. The chip shows the raw words and, beside them, the tidy the gateway returns behind its deletion-only guards (dictation_tidy). Then:

choice key say (after the wake) types
send it Return “send it” the tidy
say it plain Shift+Return “say it plain” the raw words
scratch that Esc “scratch that” nothing

The three keys are system-wide only while a review is open. A tidy the guard refused is never offered: the chip says “plain only” and Return types the raw words. After ten seconds with no choice nothing is typed, and the chip says so.

hold_to_talk_style picks the tidy’s style (clean, email, chat, code), and the dictation_tidy_request carries it. With no style set (the default, “auto” in the tab), the gateway picks one for the app the hold went down on: the loadout’s [dictation.styles], then its built-in table, then plain. The chip names the style applied: the gateway’s dictation_tidy.style when its reply carries one, else the style Glyph sent, else auto.

[global_shortcuts]
hold_to_talk = "Globe"
hold_to_talk_literal = false   # review mode; absent or true = type at release
# hold_to_talk_style = "clean"
# screen_agent_socket = "~/.local/state/vulpine/screen/screen.sock"

Glyph reads ~/.config/glyph/config.toml at launch, so a relaunch applies a hand edit. The gateway side needs the screen agent running. The gateway admits holds unless the bound loadout says [dictation] hold_to_talk = false.

Dictation controls: Voice → Hold-to-talk, the chip and vulpine-glyphctl

Every control below takes the path its key or spoken verb takes. Nothing new crosses the wire.

  • The chip. During a review it shows Send / Plain / Scratch (the Return / Shift+Return / Esc path). After an insert it shows TYPED with a Scratch that button for 6 s. A click on the chip never takes the focus from the field the words went to.
  • Operations → Voice → Hold-to-talk: the switch, the key’s live route and any setup still unmet, Literal / Review, the tidy style (review mode only), a read-only stream line, Scratch that, and, while a call is recorded, a meeting line with Opt out and Forget…. Meeting minutes are on the Admin’s Meetings page.
  • Settings persist. The switch, the mode, the style and the key choice apply at once and are written to the [global_shortcuts] keys of ~/.config/glyph/config.toml. Every other line keeps its bytes, and the first write of a session keeps a config.toml.bak. The writer refuses a missing, symlinked, unwritable or unparsable file, and says so. A key choice takes effect at the next launch.
  • Scratch that erases the last insert inside the gateway’s 120 s window. Keep that has no button: say it, or run vulpine-glyphctl keep-that.
vulpine-glyphctl dictation hold [--literal|--review] [--style clean|email|chat|code|auto]   # opens the mic; nothing spoken
vulpine-glyphctl dictation release
vulpine-glyphctl dictation hold --source remote         # mic stays closed; PCM comes from `dictation feed`
vulpine-glyphctl dictation feed [--from <path|->] [--edges <path|->] [--rate 16000]   # a hold on outside PCM (remotectl, a FIFO)
vulpine-glyphctl dictation review send|plain|scratch    # an open review, as its keys
vulpine-glyphctl dictation erase-last                   # "scratch that" for the last insert
vulpine-glyphctl dictation status                       # hold, mode, style, key route, last insert — no words
vulpine-glyphctl dictation mode --literal|--review [--style s|auto]   # persisted; auto = the gateway picks per app
vulpine-glyphctl dictation on|off                       # the switch, persisted (off removes hold_to_talk)
vulpine-glyphctl keep-that                              # the gateway answers aloud
vulpine-glyphctl recall --at 15:00 [--minutes 20] | --from 14:00 --to 14:30 | --last 15 [--session current]
vulpine-glyphctl meet status | opt-out [<call_id>] | forget [<call_id>]
vulpine-glyphctl meet minutes [<call_id>|last]          # the typed minutes on one line — prints model text
vulpine-glyphctl enroll start [--seconds 30] | status | discard   # real-voice enrollment from this mic

Each verb prints one JSON line ({"ok": …, "verb": …}) and exits 1 on a refusal. meet minutes is the one verb that prints model text; every other verb prints counts, ids and reasons. enroll start records a speaker embedding from this mic (10 to 60 seconds; only the averaged embedding is kept, the audio is deleted) when [speaker] enrollment_from_mic is on and this Glyph is the voice owner.

Operations

The status capsule stays visible in every Visual Theme. Open it to see the live link, phase, session, model, capture, startup configuration and the bounded diagnostic log. When the current continuity has agent attention or settled background work, the closed capsule also shows category counts (current counts, not unread state).

Operations offers the runtime controls; authority stays in the gateway:

  • microphone on/off and the exact capture device;
  • the body (Classic, Island, Halo, Familiar, Ribbon, Printer) and the Visual Theme (Orb, Cast, LED, SVG; Cast engines: Seal, Sigil, Corona, Hyphae, Beat);
  • window dragging from the overlay or its move handle;
  • transient assistant subtitles (Look);
  • the Halo’s and the Island’s glances (Voice → Glances): Level meter, the mic and Vulpine’s voice as two 8-segment bars from the Glyph’s own analyzers (apps/glyph/src/plugins/levelMeter.ts), and Agent attention, how many herdr panes wait and which agent waited last (apps/glyph/src/plugins/glances.ts). Each is dark when there is nothing to show, still under reduced motion, and never a click target;
  • Persona and Voice Profile, as the gateway reports them. When a Persona has no voice assets of its own, the deployment voice stays visible and voice switching is off;
  • the model, as the gateway advertises it;
  • interrupt, new session and reconnect;
  • copy and clear the diagnostic JSON.

The five groups, the face mirror and the look

Operations opens on five groups:

  • Look: the body (Halo; Classic, Island, Printer, Familiar and Ribbon with Labs on, and a saved one is still drawn), face and face variant, mood color, face opacity, ring light, panel look and the glances. With Labs on, also Fox follows replies and the portrait.
  • Voice: microphone on/off, capture device, Persona and voice, subtitles, and hold-to-talk (key, Literal / Review, tidy style, Scratch that, the meeting line; above).
  • Conversation window: its switch, Show / hide, Cards open in, Open on a show and the Capture button.
  • Connection & privacy: pairing (Connect to your gateway), the gateway on another Mac, the session (interrupt, new session, reconnect, connect), model, room, Share the front app with the brain, Permissions and microphone access.
  • App: the version and the updates (Sparkle on or why off, an update found, the last offer the update guard checked and its verdict, and Check now), Relaunch and Quit, the shortcuts (Mic on or off, and Show or hide: Cmd-Opt-Space), Command line, a line naming what lives in the Admin (live sessions, the events log, latency and meeting minutes), and the Labs switch. With Labs on, the collapsed Labs & diagnostics group holds the read-outs: live state with Copy diagnostics (this Glyph’s own client events, redacted, as JSON), the effective configuration, the conversation window’s health lines, Shell, Footprint, Owner export, hold-to-talk’s Trailing capture and stream line, and the Herdr attention and background-work cards.

A config that still names the face keys show_scanner or show_orb loads, and Glyph logs once that they are ignored.

Above the groups, a face mirror draws the current face small, with the body, the face, the mood and a one-line look summary (opacity, ring light, subtitles). The Voice group shows a badge while a dictation review waits, and the App group the attention count. A finalized transcript that waits to be saved shows its Retry save above every group.

The look controls apply to every face:

  • Mood color: Auto follows the mood Vulpine sets as it talks. A color pins that mood.
  • Face opacity: 20 to 100 percent, so you can see your work through the face.
  • Ring light: an on/off switch.
  • Fox follows replies (Labs): on by default. After each reply the gateway’s decision model picks a face or a gesture for the fox (the motion plan, [decision_shadow] motion_plan). Off asks the gateway to stop for this Glyph’s session (motion_plan_switch). The position is the webview’s own preference, not faces.json.

A body picked in the Look group switches live. Glyph moves and resizes the window and saves the choice to chassis.txt in its state directory. Face picks and the look are saved to faces.json in the same directory, so glyphctl, the Admin and a fresh webview read the same choices. Subtitles are not saved.

glyphctl drives the same controls:

vulpine-glyphctl chassis <classic|island|halo|familiar|ribbon|printer>
vulpine-glyphctl face <orb|cast|scanner|phonogram> [variant]   # vulpine-glyphctl face lists the variants
vulpine-glyphctl look [--opacity N] [--ring on|off] [--mood <mood>|auto]
vulpine-glyphctl subtitles <on|off>

look needs at least one option. --opacity takes 60, 60% or 0.6. --mood takes auto or one of steady, wry, sassy, earnest, reflective, hushed, menace, playful, lively or dreamy. vulpine-glyphctl status prints the chassis, face, look and subtitles.

Glyph starts with the microphone off. Turn it on from Operations or the audio shortcut. vulpine-glyphctl audio enabled|disabled returns only once capture has really changed. vulpine-glyphctl room <name> sets the room Glyph declares at hello ([vulpine] room; room none clears it). Subtitles show only the current turn and are never saved. The Herdr attention and background-work cards show ids and states only, never transcript, output or paths.

Owner, playback and reads from vulpine-glyphctl

vulpine-glyphctl owner [--json]      # the ADR 0024 owner: attachment, owner id, lease generation, hello mode
vulpine-glyphctl playback [--json]   # the last played segments (≤ 16, newest first)
vulpine-glyphctl read <url> [--restart] [--timeout <secs>] | --text <text> | pause|resume|next|previous|restart|stop|where

owner and playback exit 1 until the webview has reported one, and the resume token is never printed. A read command waits for the gateway’s answer, at most 70 s.

See docs/frontend-interfaces.md for the complete Vigil and Glyph interface inventory and authority boundary.

Diagnostics and Session cards, Relaunch, and [owner] export

Operations shows these read-outs:

  • Labs → Shell: what vulpine-glyphctl doctor prints, from inside this Glyph (the doctor_report command): the socket path, whether it answers vulpine-glyphctl now, the pid, the launch (Finder, the Dock or launchd; a shell’s TMPDIR; XDG_RUNTIME_DIR), the launch TMPDIR, the requests in flight and the WebGPU word. Refresh reads it again.
  • Labs → Footprint: main, WebKit, helpers, total and lifetime max from the reporter’s read, the read’s age, and “Reported to the gateway N s ago (session …)” or why not. Read now reads it here.
  • Labs → Live state: the draw loop (parked, drawing or stopped) and its idle poll.
  • Labs → Owner export: the Phone can answer switch. On, the owner receipt is exported for a phone to answer this Glyph’s dialogs (“Phone can answer: clients/foxline-glyph/owner.json · gen N”); off removes the file and stops the export. The switch is written to config.toml and read at launch:
[owner]
export = false   # absent or true = the phone can answer
  • Relaunch Glyph (Operations → App): Glyph quits and reopens its bundle with the same launch environment, so the socket path and vulpine-glyphctl stay valid. A dev build outside an app bundle refuses. vulpine-glyphctl relaunch does the same from a shell.

The welcome window: the privacy grants

The welcome window has one row per macOS privacy grant the Glyph uses: what it is for, its live status and one button. The rows are numbered steps, required first, and only the current row’s button is live. Nothing asks at launch. “All set” shows once every needed row is on.

  • Microphone (required) uses macOS’s own prompt.
  • Input Monitoring is for the Globe key’s helper, required only when hold_to_talk names the Globe key. While no hold key is set, the row offers Use Globe, which writes hold_to_talk = "Globe" and starts the key with no relaunch, and Not now.
  • Accessibility is required while the conversation window is on, so its ⌥⇧Space does not also reach the app in front. Screen Recording joins while the window’s Capture button is on.
  • For a list grant, Open System Settings opens the exact pane with a drag card: drag the Vulpine.app row into the list. A grant that needs a relaunch makes the window relaunch the Glyph, at most once in two minutes.

Typing and screen capture need no grant of the Glyph’s own: the screen agent holds them. The window opens by itself on the first launch and whenever a required grant is missing; its switch is saved as auto_show in ~/Library/Application Support/<bundle id>/welcome.json. vulpine-glyphctl onboarding opens it, and vulpine-glyphctl status prints one Grant line per grant (Grant microphone: granted (required)). Other ways back: the right-click menu’s Finish setup… (only while a required grant is missing), Operations → Connection & privacy → Permissions → Review, and the Admin’s Glyph section.

Launch the showcase: vulpine-glyphctl showcase

vulpine-glyphctl showcase [--tile <id>] opens the native visuals showcase on the Glyph’s Mac, one at a time. The showcase must be installed beside the Glyph binary or in ~/.local/bin. The verb prints one JSON line: opened, already_open, or a refusal (not_installed, old_build, unknown_tile, bad_tile, spawn_failed). The brain can ask for it too (brain_frontend_control, action: "showcase"), for an owner-local caller only.

vulpine-glyphctl on the PATH: App → Command line

vulpine-glyphctl ships inside the bundle. Install vulpine-glyphctl in PATH (Operations → App → Command line) writes a small shim that finds the installed app each time it runs, so it survives upgrades. It writes into the first folder on your login PATH among /opt/homebrew/bin, /usr/local/bin, ~/.local/bin and ~/bin that you can write to, else ~/.local/bin. Install in /usr/local/bin… uses macOS’s administrator prompt; Glyph never runs sudo. Remove deletes only Glyph’s own shim. The card also shows the bundle id this Glyph runs under (com.voidfab.vulpine).

Trailing capture and footprint reporting as switches

Two switches each write a config key. A switch applies to this session at once and is saved to config.toml through src-tauri/src/config_writer.rs, the one writer, behind its guards (the operator’s own regular file, a .bak once per session, an atomic write, only the owned key touched). A refused write holds for this session only, and the card says so:

  • Trailing capture (hold-to-talk) writes [global_shortcuts] hold_to_talk_trailing_capture.
  • Labs → Footprint → Report to the gateway writes [footprint] report. Off stops the once-a-minute reports to the gateway (the Admin then shows no “Glyph footprint, reported” for this Glyph), across binds. Read now still reads here.
[global_shortcuts]
hold_to_talk_trailing_capture = false   # absent or true = on

[footprint]
report = false                          # absent or true = on

The webview publishes both, and screen_context_share (Connection & privacy’s front-app switch; absent = on), as switches.json in the state dir, beside faces.json and panel-look.txt (the set_glyph_switches command, booleans only). The Admin’s Glyph section shows them as the Trailing capture, Footprint reporting and Front app to the brain rows, after the Panel look. Until a Glyph publishes, the rows say “on (Glyph default, nothing published yet)”.

The conversation window as the Glyph’s sidecar

The conversation window runs as the Glyph’s sidecar process (ADR 0046), drawn in GPUI (convo-gpui). The freya window (convo-freya) is frozen and stays the fallback.

  • Operations → Conversation window: an on/off switch. On, the Glyph starts the window once it knows its session (<window> --observe <[vulpine] url> --session <id> --sidecar --hidden-start). The window observes this Glyph’s session read only and follows it across reconnects. It quits with the Glyph.
  • Show / hide slides the window in and out; its own ⌥⇧Space does the same. On the Halo, the level meter on the display’s edge is a 44 px button that opens and closes the window.
  • Cards open in: the conversation window (the default) or the corner card, saved as [conversation_window] cards. Open on a show (on by default) reopens a closed window when a card arrives.
  • Crashes. A window that exits unexpectedly starts again after 1 s, then after 4 s. A third crash in a row gives up, and the card says “Conversation window stopped” until Show / hide or the switch starts it again.
  • vulpine-glyphctl doctor prints the window’s health and a signing line. matches or matches_shape keeps the macOS privacy grants; cdhash (an ad-hoc build), drifted (another bundle id or team) and local_identity (a local certificate) say why macOS asks again. The release gate reads the same bundle-identity.json.
  • The binary: [conversation_window] path, else [conversation_window] binary (a bare name), else convo-gpui and then convo-freya, each beside the Glyph binary and then in ~/.local/bin; never PATH.
  • What the window draws is fed through the sidecar envelope (sidecar-envelope.v1, draft; crates/sidecar_envelope).
[conversation_window]
enabled = true                       # absent or false = off; the switch writes it
# binary = "convo-freya"             # optional: one window by name (default: convo-gpui, then convo-freya)
# path = "~/.local/bin/convo-gpui"   # optional: one window by path; the switch writes neither
# avatar = true                      # the Avatar portrait (Look → Portrait writes it); absent or false = off
# avatar_model = "~/Live2D/me/me.model3.json"  # the Live2D model it draws, or a .vrm; absent or "" = the built-in fox
# ascii_camera = true                # Look → Portrait → ASCII camera: the fox window opens on its Camera look
                                    #   (the camera starts only on its Start camera button; the welcome window's Camera row asks)
# avatar_hood = false                # Look → Portrait → Hood: absent or true = the avatar wears its hood
                                    #   (when its model has a hood parameter); false starts the window with --avatar-hood off

Look → Portrait → Avatar (Labs; off unless avatar = true) opens a fox window beside the conversation window on a Live2D or VRM portrait, puppeted by avatar-puppet.v1. The Model field names a .model3.json or a .vrm on this Mac, read in place. The portrait’s mouth follows the played audio and the reply’s words, and its face and gaze follow the session’s avatar actions.

The orb drawn natively, the web page kept as an option

The overlay’s Classic disc is drawn by orb-gpui, a native GPUI window one level over the overlay, placed on the face’s stage, with the mouse passing through to the face’s button. It uses 27.7 MiB at rest and draws nothing while the face is still; the WebKit orb measured 72 MiB.

  • Operations → Look → Orb drawing: “Native (lighter)” (the default) or “Web page”, saved as [overlay_orb] drawn_by.
  • The page draws the disc whenever the native orb cannot: another look than the Classic disc, the binary not found, a failed start, three unexpected exits in a row, or “Web page” chosen.
  • The binary: [overlay_orb] path when set, else orb-gpui beside the Glyph binary and then in ~/.local/bin; never PATH. The orb never dials the gateway.
[overlay_orb]
drawn_by = "native"                # or "web"; absent = native; Look → Orb drawing writes it
# path = "~/.local/bin/orb-gpui"   # optional: one orb by path

The right-click menu

The right-click menu opens at the pointer: Show / Hide conversation window, Settings…, Finish setup…, Check for Updates…, Quit Glyph. It closes on Escape, on a press outside it (in another app too), on the hide shortcut, and when the Glyph loses focus. Show / Hide conversation window is grayed, with the reason, when no window runs and a press could not start one. The status pill is a toggle: its second click closes Operations.

Panels on every body

A render frame from the brain or a tool (pi_show_render: a card.v1 such as Forecast or Fleet status, or one of the five chart kinds) draws as the panel kit’s card in the body’s panel place (src/panels/GlyphPanels.tsx, the chassis’s renderCard slot). The place belongs to the body, so every face gets it. Each body puts the card where it never covers the status pill or the error toast:

Body Where the panel goes Most room (pt, as of 2026-10-18) Fit Dismiss
Classic (250 × 280, floating) Over the disc, above the lip; the chip column stays over it 234 wide, 176 tall line ×, Esc*, its ttl (held while the pointer is on it)
Island (560 × 520, top center) A sheet below the island: under the capsule, its pill and its toast, centered 420 wide; to 8 pt above the window’s foot (about 435 tall at rest, 345 while it speaks) full (brief while it speaks) ×, Esc*, its ttl (held)
Halo (the display) Lower right, over the toast and pill, clear of the summoned face and the dock 400 wide; from 36 pt under the top to 140 pt over the pill full ×, Esc*, its ttl (held)
Familiar (the display) Lower right, over the toast and pill; lower left while the familiar itself sits lower right 400 wide; from 36 pt under the top to the toast full ×, Esc*, its ttl (held)
Ribbon (display width × 520, bottom edge) Above the strip’s right end, over the toast and pill 400 wide; from 12 pt under the window’s top to the toast full ×, Esc*, its ttl (held)
Printer (280 × 480, floating) Under the case, across the window, over the oldest slips 264 wide; from 104 pt down to the toast brief ×, Esc*, its ttl (held)
  • Fit: full is the card as sent, brief its header, headline and summary, line its header and summary. Every fit keeps the summary the reply says aloud. When the room shrinks (the Island while it speaks), the card steps down one fit before it paints, and back up when the room grows. A card is never cut off behind a hidden scroll.
  • Dismiss: the ×, a click on the card, or the frame’s ttl (five minutes when it sets none). Up to two older cards wait under the top one. Esc dismisses only where the page has the keys (the showcase, a browser): Vulpine.app never takes the keys from the app you work in.
  • The look: Operations → Look → Panel look (Match theme, Graphite, Field kit, Porcelain) applies on every body. Show a sample panel draws the forecast with no gateway.

Themes: Porcelain, Night glass, Tidewater and Brass

Four Glyph Themes ship in apps/glyph/src/theme/themes/: Porcelain (warm and light: bone, lacquer, one red listening light, a still matte orb), Night glass (dark: violet with cyan and magenta, a holographic orb), Tidewater and Brass (warm brass and cream on a near-black case, the look before the default became the Gateway app’s). Brass is built into the app (src-tauri/src/theme.rs), so it binds with no install. Every text pair in Porcelain, Night glass and Tidewater meets WCAG AA.

just apps::glyph-themes-install --dry-run   # what it would copy, and where
just apps::glyph-themes-install             # into $XDG_CONFIG_HOME/glyph/themes (else .config/glyph/themes at home)

A file already there that differs is kept unless --force. Then Operations → Look → Theme lists them; picking one binds it (as vulpine-glyphctl theme porcelain does), and default goes back. The chassis showcase takes ?theme=porcelain or ?theme=night-glass.

Was this page helpful?