App

The app

The dashboard as a web page, on the design system: a sidebar with your conversations, a thread with the agent's messages and every tool call, approvals inline, a composer at the bottom. It runs against a local daemon or a remote one, in any browser, and it is what the desktop app wraps.

Opening it

shibaox app            # opens the browser at the app, connected to this daemon
shibaox app --no-open  # prints the address only

Three cases, decided by the CLI:

• A remote daemon (shibaox remote set … or --remote): the daemon serves the app itself at <url>/app/; the CLI opens it with the token in the URL fragment.
• A local daemon with a network listener (listen in daemon.yaml, or shibaox serve): the same, at http://127.0.0.1:<port>/app/, with the token from SHIBAOX_DAEMON_TOKEN or the vault.
• A local daemon on its socket only: the CLI starts a bridge, a loopback HTTP server on a free port that serves the app and forwards its calls to the socket, behind a token made for that session. The address works while shibaox app runs (Ctrl-C stops it). Nothing listens off the loopback interface.

The app reads the token off the fragment once, keeps it in the browser's storage, and removes it from the address bar. Opened without a token (the daemon's /app/ typed by hand), it asks for the token on a Connect screen (the daemon is the one that served the page: the API sends no CORS headers, so another origin does not work). A refused token brings that screen back. Disconnect in Settings forgets it.

What is on screen

The sidebar: the Shiba and the wordmark, New chat, the sections Chats · Scheduled · Customize · Memory, the Recent conversations, and you (name and Settings). The Chats count is what waits for you; the Scheduled count is the routines that are on.

A conversation: the title (your first request), the agent's status (Working, Needs you, Online, Sleeping, Error), and three tabs.

• Chat: your turns and the agent's replies as they stream; each tool call as a card (tool, gist, status, duration, arguments and output on demand); a command or a protected-file write waiting for you as a card with Approve and Deny; a human node (approve-push and the like) as a message with a note field and the two buttons. While a task runs, Steer in the top bar sends it a note (it stops and starts again with it). The composer sends the next turn (Cmd/Ctrl+Enter) once the previous one settled; Stop cancels the live turn. The model label is the model of the next turn: Model in the top bar picks one for this conversation (in memory until a turn runs on it), Settings sets the one new chats start on.
• Tasks: the runs the orchestrator dispatched in this conversation, with status and cost, Open, Steer (a note for a running one), Cancel, and Resume with a budget for one that paused on its budget; what a dispatched run asks for (a command approval, a human node) shows on its card and in the chat; a decide node's card says the choice, how sure, and who decided (jev, model:<ref>, scripted). Each reply names the model that wrote it after the time (from the run's usage). A turn Jev routed has a muted line above the reply, Routed by Jev · media (0.98) · cheap (the intent, how sure, the tier); your message stays as you wrote it. The model menu of a conversation has a search field when the list is long.
• Logs: every node, gate (with each check), decision, approval (who, via which channel) and the run summary; Open audit fetches the full audit document with your token and opens it.

Chats lists every conversation with its project, last activity, cost and status. In a conversation, Model in the top bar picks the model of its next turns from the configured ones (the org's tiers otherwise).

Scheduled: the daemon's routines (Routines) as cards: name, description, the trigger in words ("Weekdays at 09:00", "On issues labelled bug"), the next run, the last run (status, cost, when; it opens as a conversation), and badges for Paused, "from the org", a model, and "Auto approvals" or "Skips approvals". Search and sort (next run, name, last run). Each card's menu: Run now, Pause/Resume, Edit, Duplicate, Open last run, Remove (asks first). New routine offers three ways: Create with Shibaox (a sentence becomes a draft for you to check), Set up manually (the form), From a template (security scan, daily briefing, issue triage, fix labelled bugs, monitor CI, weekly review, dependency updates). The form: name, instructions, project, model, a frequency (manual, hourly, daily, weekdays, weekly, monthly, custom cron, GitHub issues/PRs/checks, a URL, a file, a command, with the result in words), permissions (manually approve, automatically approve, skip all approvals, each with what it means) and advanced settings (workflow, adapter, budget per run, daily cap, how watchers fire, the check interval). Editing a routine that came from org/routines/*.yaml detaches it from the file, and the dialog says so.

Memory: the project profile (git branch, stack, package manager, test command, files), the org (adapter, tiers, judge, budget), and where the vault notes live.

Customize (#/customize): everything that extends Shibaox, in five tabs: Skills · Connectors · Plugins · Keys · Models. The tab is part of the address (#/customize&tab=keys), and the old #/skills and #/integrations links land on Skills and Connectors. Skills, Connectors and Plugins have the same bar: Yours | Discover (a dot on Yours when something there needs you: a skill no role uses, a connector missing a key or failing its test, a plugin half set up; a screen reader hears "needs attention"), a search, and + Add; Skills (Discover) and Connectors also have a Category filter, Plugins has none. When the org cannot be found the screen says why, with Retry. Cards sit two to a row (one on a narrow window). The org's files stay the source of truth (org/skills/<id>/SKILL.md, org/catalog/*.yaml, org/roles/*.yaml, the vault): the screen edits them through the daemon.

• Skills: Yours lists the org's skills with the roles that use them (or "Not used by any role"); each card's menu has Open (its SKILL.md rendered in a side panel, with its path and Copy path), Roles… (a checkbox per role) and Remove (asks first; while a role uses it, "Detach from roles first" must be ticked, and when the daemon says roles still use it the dialog names them: "used by assistant — detach?"). Below them, the org's Workflows, each with Run task (a request, optionally a project and a model: a run in a worktree, or in place for a conversation workflow, that opens as a conversation). Discover lists the built-in skill sources (Anthropic's skills, Higgsfield's) grouped by source; the category filter offers each source and the folders its skills actually sit in (a source with its skills at the top adds none). A source that cannot be read says why, with Retry. + installs one and opens its Roles dialog. + Add: From a repository (a GitHub owner/repo[/path] or an https:// git URL, or, with a daemon on this machine, a file:// URL or a path: the dialog lists every folder with a SKILL.md, you pick which to install), From a folder (a path on the daemon's machine), Write a skill (an id and its SKILL.md). When nothing is added the dialog stays open and says why for each skill (already in the org, not a valid id, a symbolic link, too large, not found, the copy failed); when some are, the rest and any file left out (over 1 MB) are a note.
• Connectors (MCP servers): Yours shows each server of the catalog with its transport and target, the roles that use it and its keys (a missing key is a badge that opens Keys on that key), Test (starts it on the daemon and lists its tools, inline), and a menu with Roles…, Edit… (the server as written in its catalog file: arguments, environment, headers, bearer command, tools and timeout kept; saving replaces the file and makes the ticked roles exactly the ones that use it) and Remove (taken out of every role first). Discover is the built-in registry (GitHub, Notion, Playwright, Context7, Linear, Sentry, Supabase, Figma, Firecrawl, Exa…) by category, with the vendor and a verified badge for official servers; + opens "Add ": the keys it needs (set them right there, with a link to get one), the roles to attach (assistant ticked), Add. + Add → Custom connector: id (letters, digits, - and _; no : or __, and not shibaox or graphify), description, transport (http with a URL, headers where ${KEY} becomes a vault key, a bearer command; or stdio with one command, its arguments one per line and a fixed environment), the keys it needs, a tools allowlist, a timeout, the roles.
• Plugins: partner integrations with their own setup, built in. Higgsfield works in two modes, with an Account | API switch (named "Mode"; it opens on the mode chosen in Use for generation, else the one in use, and follows a new choice; you can still switch by hand). The mode tasks use now carries a small dot ("in use" to a screen reader). Each panel has its own checks, actions and what it brings: Account (whether the CLI is installed and logged in, the account's plan and credits, whether its MCP answers; Log in opens the browser login on the daemon's machine, Create an account is an affiliate link, Install command copies it and it shows whole when the CLI is missing; generation spends the plan's credits) and API (a developer key from open.higgsfield.ai: API key saved and API key valid, as the daemon's probe answered; generation is billed to that developer account; it also brings the higgsfield_api_* tools; API docs opens docs.higgsfield.ai). Both modes add Shibaox's own built-in skills (higgsfield; the API also higgsfield-app). Connect API key opens a dialog with one password field ("Paste the API key copied from open.higgsfield.ai. Paste it as-is.") and Get a key; Enter saves; a key that is not an id:secret pair (checked as the daemon does) is refused before anything is sent. Once a key is saved the button reads Manage API key (decided from the API mode's key, so the button and the dialog agree): the masked key and its validity, Replace (Cancel goes back to Manage), and Remove (asks first and waits for the daemon, then closes; a key from the daemon's environment cannot be removed here). Use for generation (Auto · Account · API) writes partners.higgsfield.mode in daemon.yaml (Auto = the API when a key is saved, else the account; a running task keeps what it started with; picking the current choice again changes nothing), and Now: says what tasks use (API, Account, or nothing set up). Use for generation is changed from the daemon's own machine only (it writes daemon.yaml): a page opened from another machine gets a refusal. The key goes to the vault like any other key (the token suffices). GitHub (gh and its token: GH_TOKEN or GITHUB_TOKEN, either one), Telegram (the bot token, a paired chat, the channel running: Ready needs all three; Pair with my Telegram waits up to a minute while you send /start to your bot ("Open your bot in Telegram and send /start now…"), then says Paired with chat or why not; Send a test message says Sent ✓ or why not; pairing is for the daemon's own machine; it brings the telegram_send tool), TypeSafe / Jev (its key; Jev decides, Jev routes requests with the last route, Jev runs checks; Use Jev for decisions when an LLM decides, Route requests with Jev / Stop routing requests, each saying what it did and reading the org again; it brings the typesafe-ai skill). Each card lists its checks, its keys, its actions (links open in a new tab) and what it brings (a connector, a skill: Shibaox's built-in one when it has it, else from the source of the same vendor) with a button to add each. Search also reads the modes' keys and check labels. Yours = plugins with something configured (or a mode set up, or a generation choice made, such as API before its key); Discover = the rest. No category filter: there are four.
• Keys: the vault, organised. Needed now: every key the org's tiers, its roles' models, its connectors and the plugins read, with who needs it as badges (tier cheap, role reviewer, connector github, plugin github), missing ones first (a plugin not set up at all needs nothing yet: its keys wait in Other, unless one of its modes was chosen by name: Higgsfield on API needs HIGGSFIELD_API_KEY now; keys a plugin takes either of, such as GH_TOKEN or GITHUB_TOKEN, are one row, met by either); Set a value (never shown again) or Unset it (a key from the environment says so and cannot be unset here). Providers: one row per model provider with its key, its status and how many models it unlocks (the set and needed ones; Show all providers for the rest). Other: Shibaox's own keys (Telegram, GitHub, the daemon token, TypeSafe, the Higgsfield API) and yours, with Add key (a name in capitals, digits and _). #/customize&tab=keys&key=NAME focuses that key.
• Models: the org's Tiers (strong, cheap, decision, judge, budget per run, and Jev routing: Default, On or Off; Save tiers), every model the daemon knows with a search and a filter (All, Ready, Missing key, Missing runtime, Local), its provider, status (a missing key opens Keys on it), context window and price per million tokens (128k, $0.30/$2.50; "—" when unknown; 60 rows at a time with Show 60 more), and Decisions: who decides for the org (the decision tier: an LLM such as openrouter/typesafe/jev-router, or Jev, TypeSafe's typed API, with whether it is usable and why not) and the latest decisions across runs (node, choice, confidence, who decided, each a link into its conversation: decide nodes, judged gates, and Jev's routing of chat turns, router and router:tier by jev).

Settings: theme (light, dark, system), your name, the project, org and model new chats use, the daemon's address and version, Disconnect.

Replies as documents. The agent's text renders as Markdown: headings, lists, task lists, quotes, tables, links (they open in a new tab; only web and mail links are links), and fenced code with the brand's syntax colours (Copy on every block, long blocks clipped with "Show all"). An unlabelled block that is plainly CSV shows as a table. Tool calls and files appear where they happened in the reply, not after it. Your own messages keep their line breaks and show inline marks only.

Files a run produced. A file the run wrote shows as a chip in the reply and in the "Outputs" row under the top bar. A chip opens the file in a panel on the right: CSV as a table, Markdown as a document, code with colours, images inline, anything else says there is no preview; Copy and Download (or, on the desktop, Open and Save as…) are in the panel's head and always carry the whole file, while the view stops at 2 MB. The panel reads the file from the run's workspace through the daemon, so it works for remote daemons too; .env, .git and the project's protected files are never shown. The same files from the terminal: shibaox files <runId> [path].

Attachments. Drop any files on a conversation (or press + in the composer): they show as chips and go with the next message, up to 20 files and 25 MB. The daemon puts them under attachments/ in the workspace (kept out of git through the repository's local exclude file, never committed by a git node), names them for the model at the end of the message, and the model reads or edits them with its file tools; they show as chips on your message and under Outputs, with a thumbnail when they are images or video (in the composer too). A message that the daemon refuses (a protected name, too large) keeps its text and files in the composer. The bolt is Actions: run one of the org's workflows in this conversation (the text becomes its input), prefill a Higgsfield image or video prompt, or attach files. The mic listens where the browser can (Chrome) and puts the words in the text; it is hidden in the desktop app and in browsers without speech recognition.

Images, video and audio. Ask for an image, a clip or a voice, or attach a picture and ask for one made from it ("the same dog in Parede"): the orchestrator uploads the reference to Higgsfield for you (higgsfield_upload, only files under attachments/ or outputs/) and generates with it. The orchestrator generates with Higgsfield (its MCP, signed in through the Higgsfield CLI's login, or the higgsfield command), saves the result under outputs/ in the workspace with download_file, and the file shows in the reply with a preview (images inline, video and audio with a player). Credits are spent on the logged-in Higgsfield account; see Customize → Plugins → Higgsfield.

Code that becomes a file. The panel previews what it can: CSV and TSV as a table even when the rows are uneven, JSON pretty-printed, Markdown rendered, code with colours, text, images; anything else says there is no preview and still offers the actions. Every code block and CSV table in a reply has Open: the block opens in the same panel as a file (named from the fence, a file: comment, its first function, or its kind: fibonacci.js, table.csv), with Copy and Download, and, when the conversation has a finished run with a workspace, Save to project: a path inside that workspace, written through the daemon (PUT /runs/:id/files/content), listed under Outputs and in shibaox files as a file of yours. The orchestrator is also told to create requested files with its own tools; Open is for the times it only shows the code.

When a dispatched run ends while its conversation is open, the app tells the orchestrator (an event turn), as the terminal dashboard does; the orchestrator may then answer or dispatch more.

The desktop app (macOS)

Shibaox.app is the same app in its own window, without a browser or a terminal. It is a dmg for Apple silicon and Intel, attached to each release (Shibaox-<version>-arm64.dmg, Shibaox-<version>-x64.dmg). Releases built with the Apple secrets in place are signed with a Developer ID and notarized, and open like any app. A build without them is signed ad hoc: the first launch is refused, then allowed once under System Settings, Privacy and Security, "Open Anyway" (or xattr -dr com.apple.quarantine /Applications/Shibaox.app).

On the desktop the panel's Open hands the file to the app that reads it (Excel or Numbers for a CSV, your editor for code, the browser for HTML; kinds that would run rather than open are refused), Save as… is the macOS save dialog, and a file saved to the project gets Reveal in Finder. In a browser the same place offers Download.

The app keeps itself current: it checks the releases shortly after it starts and every few hours, downloads a newer version in the background and asks once per launch, "Restart now" or "Later" (later, it installs when you quit). Shibaox → Check for Updates… checks on the spot. What it did is in ~/.shibaox/desktop.log. The browser app inside it updates with it; the daemon is updated separately (shibaox upgrade, see CLI reference).

It needs the CLI installed (npm i -g shibaox): on launch it talks to the local daemon through its own bridge on a loopback port (7434 or the next free one) and starts the daemon when it is not running (the launchd service when shibaox daemon install set one up, else the installer's launcher, else shibaox daemon start --detach through your login shell; the daemon logs to ~/.shibaox/daemon.log). With shibaox remote set <url> <token> done, it opens that remote daemon's app instead. When no daemon can be reached, it says why and offers "Try again".

Links out of the app (a PR, the wiki) open in your browser. The window has no Node access; the bridge's token is random per launch and never leaves the machine.

Themes and the design system

Light ("warm paper") and dark ("night") follow the system by default. Everything on screen is a component of the Shibaox design system (tokens, Geist and Bricolage Grotesque, the mascot), vendored into the app package at build time (scripts/sync-design-system.sh).

Security

• The app itself (HTML, scripts, styles) is public on the daemon's listeners: it holds nothing. Every call it makes carries the bearer token, and a token is shell access on the daemon's machine: the address shibaox app prints contains it, so treat that address as you treat the token (do not paste it in chats; the fragment never reaches a server, but it sits in the browser's history until the app strips it and in the browser's storage until Disconnect).
• The bridge's token is random per session and dies with the command. The address (token included) is passed to the system's opener (open, xdg-open, start), so it is visible in the process list for a moment.
• The app never renders model output as HTML: text is text.

Troubleshooting

• The daemon listens on the network but its token is not here: run shibaox app where the token is (SHIBAOX_DAEMON_TOKEN, or shibaox keys set SHIBAOX_DAEMON_TOKEN … on the daemon's machine), or open http://<host>:<port>/app/ and paste the token on the Connect screen.
• the browser app is not installed next to this daemon: npm i -g shibaox@latest (the app ships with it, as @wizardingcode/shibaox-app); a daemon started from a development checkout needs pnpm build.
• A blank page: the daemon must be 0.2.1 or later (shibaox daemon stop restarts it on the new build).
• The desktop app says shibaox is not in the PATH: your login shell (.zprofile, .zshrc) does not find shibaox (npm i -g shibaox, or start the daemon in a terminal and press Try again). exited with …: the daemon refused to start, ~/.shibaox/daemon.log says why.