Administrative API and web tools
The administrative API and web-tool layer extends the API gateway with a local control surface, Code sessions, model discovery, request shortcuts, and Anthropic-compatible web search and fetch support. It keeps control data on the server while returning selected tool results as streams for clients that use the Anthropic endpoints.
Administrative surface
The administrative surface gives an operator one place to inspect provider readiness, change server settings, manage connected accounts and custom providers, connect desktop tools, and use local model workspaces. It is separate from normal model request routes and is intended for use on the machine that runs the server.
Local administration
The /admin page serves the control UI, and /admin/api/* provides its data and actions. The server accepts these routes only when the client address, request host, and browser origin identify the local machine. The same boundary protects the administrative data and action APIs.
The UI presents five views:
- Providers: provider state, local provider checks, connected accounts, custom providers, and provider configuration.
- Model Config: model choices, fallback order and API-key selection, reasoning settings, and web-tool settings.
- Messaging: messaging and voice settings.
- Integrations: connections for VS Code Chat, Claude Code in VS Code, Codex in VS Code and the Codex app, Claude Code through JetBrains ACP, Claude through the desktop app, and DSH Desktop.
- Code sessions: a code-session library and a project-folder conversation view.
The page reads field and provider descriptions from the configuration response. This keeps the visible form aligned with the server's current configuration rules instead of making the browser own a second settings list. The browser uses a responsive dark control layout with a shared action area for normal settings views, while the Code session view uses shared controls for model selection, reasoning choices, message composition, transcript display, and responsive layout. Custom providers use the same provider area and can supply their own endpoint, credentials, model IDs, and reasoning format.
References: src/…/admin_routes.py• L104-165 src/…/admin_security.py• L58-67 src/…/index.html• L30-239 src/…/admin.js• L26-65 src/…/admin.js• L211-241 src/…/admin.css• L106-124 src/…/admin.css• L810-939 src/…/session_ui.js• L15-211
Configuration lifecycle
Configuration changes follow a validate-then-apply flow. The browser sends only changed fields, and the server filters those fields against its known configuration keys before it applies them. The same flow creates, updates, and removes custom providers through a separate provider mutation.
The result tells the operator whether a restart is needed. The UI marks settings that wait for a restart and returns to the page after an automatic restart. It reports credential checks and clearly marks keys that were saved but could not be verified. It also keeps an explicit reconnect action when the server does not return within the restart window.
References: src/…/admin_routes.py• L128-150 src/…/admin_routes.py• L530-531 src/…/admin.js• L1376-1416 src/…/admin.js• L1455-1533 src/…/admin.js• L1569-1657
Provider and account status
Provider routes give the operator a view of readiness rather than a model response. They report provider state, test providers, check local provider URLs, refresh discovered models, manage connected-account login, and manage custom provider definitions.
Local provider checks are requested one provider at a time. Each request reports a missing URL, a reachable service, or an unavailable service, so a slow or failed check does not delay results for other local providers. Connected-account status is not kept in browser caches, and the UI polls while an interactive login is in progress. A completed connection refreshes the model choices used by the settings and Code session views. When background model discovery fails, the provider card shows the server's specific error when one is available instead of only showing a generic failure.
References: src/…/admin_routes.py• L168-264 src/…/admin.js• L317-438 src/…/admin.js• L487-543 src/…/admin.js• L638-754 src/…/admin.js• L781-839 src/…/admin.js• L1660-1741
Integration connections
The Integrations view helps an operator point supported coding clients at the running server. Each connection reports its current state, shows the local settings it will change, and supports a later disconnect without mixing those changes with the main provider settings.
The VS Code Chat, Claude Code, JetBrains, Codex, desktop, and DSH flows tell the operator when the external client must reload, restart, reopen, or start a new chat before the new connection takes effect. Disconnecting DSH Desktop also tells the operator that existing sessions need another model, while new sessions can use the changed default. VS Code Chat manages its model group without changing the operator's selected models.
Integration state is refreshed in the background after an action. The UI reconciles short updates that polling may miss and keeps a failed action available for retry. This prevents the control surface from showing a completed connection while the external client setup is still pending.
References: src/…/admin_routes.py• L267-486 src/…/index.html• L67-235 src/…/admin.js• L1959-2007 src/…/admin.js• L2038-2629
Code sessions
Code sessions provide a local workspace for asking a supported coding harness to work in an existing project folder. The operator creates a session with a folder, chooses a model and thinking effort, sends work requests, watches the run, and can stop or remove the session without removing the project files.
The Code session view combines a searchable session library with a transcript of user requests, assistant output, reasoning, and tool activity. The server can pause a run for approval, permission, question, or tool-input answers; the operator submits those answers from the same view. A live event feed keeps session state, run state, prompts, and history aligned across tabs, while reconnect and resync states prevent actions against stale data.
The workspace uses a full-height transcript and composer layout. It keeps unsent text in the current browser tab and retains the selected provider, model, reasoning, harness, and access mode as session state changes. It waits for a current model catalog and a synchronized event feed before enabling session actions, then keeps the library and transcript current as runs, tool items, and prompts change.
References: src/…/code_sessions.js• L27-57 src/…/code_sessions.js• L158-243 src/…/code_sessions.js• L279-526 src/…/code_sessions.js• L603-709 src/…/code_sessions.js• L737-821 src/…/code_sessions.js• L920-1150 src/…/code_sessions.js• L1152-1364 src/…/code_sessions.js• L1433-1691 src/…/session_ui.js• L15-211
Cache and static assets
The admin surface has two related delivery rules: it serves a small versioned set of browser assets, and it prevents browsers or intermediate layers from retaining administrative responses. These rules reduce stale configuration views and limit the files exposed by the asset route.
Administrative response policy
Every path under /admin receives Cache-Control: no-store. The policy is applied to normal responses and to error responses that can bypass normal middleware handling.
The browser also requests admin data with cache: "no-store". This gives the UI a fresh view after configuration, account, integration, or Code session changes.
References: src/…/admin_cache.py• L10-49 src/…/admin_routes.py• L153-255 src/…/admin.js• L94-112 src/…/code_sessions.js• L279-365
Static asset delivery
The admin page serves index.html and allows a versioned set of CSS, JavaScript, provider logos, and application icon assets through /admin/assets/{version}/{filename}. The route returns a missing-asset error for an unknown version or name, so the admin surface does not act as a general file server.
The settings, integration, and Code session views use assets from this same allowlist. The page replaces its version placeholder when it is served, which ties the browser links to the running package version. The responsive layout provides a sidebar on wide screens and a stacked control layout on smaller screens.
References: src/…/admin_routes.py• L39-65 src/…/admin_routes.py• L91-125 src/…/index.html• L8-10 src/…/index.html• L271-276 src/…/admin.css• L106-124 src/…/admin.css• L887-983
Model catalog
The model catalog presents one model inventory through several client views. It combines models configured by the operator with model metadata discovered from providers, then shapes the result for Claude-compatible clients, Messages clients, or direct Responses clients.
Client model views
The authenticated GET /v1/models route accepts a catalog view, while GET /muse-code/models selects the direct Responses view for Muse Code. The default Claude view keeps the established Claude model set and adds configured or discovered provider models.
Direct views expose provider model references and capability data that a client can use to choose a model. Models that do not support thinking receive a separate no-thinking identity. The Responses view also advertises input limits, reasoning choices, and an inference idle-timeout value.
References: src/…/routes.py• L212-239 src/…/model_catalog.py• L23-29 src/…/model_catalog.py• L141-178 src/…/model_catalog.py• L181-251
Model discovery cache
Provider discovery is cached so model-list requests can return quickly without querying every provider. The cache stores provider model metadata, supports changes to the active provider set, and supplies prefixed model references for the catalog.
The admin model routes expose the combined view as model references with display labels for form controls. A refresh updates provider discovery and reports providers that failed without hiding models that are already configured or cached. The browser also uses the result to refresh Code session model choices.
References: src/…/model_cache.py• L10-89 src/…/admin_routes.py• L258-264 src/…/admin_routes.py• L502-527 src/…/admin.js• L1744-1788 src/…/code_sessions.js• L373-428
Request optimizations
Request optimizations answer a small set of predictable Messages requests without sending them to a model provider. They reduce network use for client support work while preserving the requested response model and the normal Messages response shape.
Fast-path responses
The Messages flow checks web-tool handling first and then runs enabled optimization handlers in a fixed order. The first matching handler returns a complete response. When none matches, the request continues to the provider.
The shortcuts cover command-prefix detection, quota probes, title generation, suggestion mode, and file-path extraction. Each shortcut is controlled by a setting, so an operator can restore provider handling when a client needs the full model path.
References: src/…/messages.py• L101-148 src/…/messages.py• L350-408 src/…/optimization_handlers.py• L44-162 src/…/settings.py• L560-581
Web tools
The web-tool layer gives Anthropic-compatible clients local handling for web_search and web_fetch. It translates supported tool requests into outbound work, checks user-controlled fetch targets, and emits the result as Anthropic server-tool events.
Supported tool requests
Forced web_search and web_fetch requests use the latest user turn as the tool input. Automatic search has a narrower contract: it accepts Claude Code's single web_search_20250305 server-tool definition and rejects mixed tools, unsupported server-tool choices, and prior server-tool history.
The web-tool setting is enabled by default, but unsupported shapes still fail as invalid requests rather than silently changing meaning. Automatic web_fetch and mixed server-tool requests are not handled by this local path.
References: src/…/request.py• L46-123 src/…/request.py• L173-207 src/…/service.py• L74-114 src/…/settings.py• L583-595
Outbound web access
Web search queries a public search page and returns a bounded set of distinct result links. Web fetch follows a bounded redirect chain, extracts readable page text, and returns a shortened document preview with its final URL and title.
Fetch egress means the network policy applied to a user-influenced URL. By default it permits configured schemes and public addresses only. Private, loopback, local, and link-local targets are rejected. A lab-only setting can allow private targets, but the connection still uses the addresses validated for that request.
References: src/…/client.py• L145-238 src/…/constants.py• L5-17 src/…/egress.py• L30-89 src/…/service.py• L250-272
Server-tool streaming
Local tool execution returns an Anthropic SSE stream with a message start, a server-tool use block, a tool result block, a text summary, usage data, and a message stop. Outbound errors become an unavailable tool result and a safe client-facing summary, while the failure is logged with limited URL information.
The stream keeps search and fetch results distinct. Search returns titles and URLs, while fetch returns a document source with citations enabled. This lets a client treat both operations as server tools while still using the right result shape.
References: src/…/service.py• L228-277 src/…/server_tool_sse.py• L30-164 src/…/service.py• L393-428
Automatic search selection
Automatic search first asks the selected provider to decide whether a search is needed. The gateway buffers that decision, replays it when no search tool call appears, or runs one local search when the provider returns the expected hidden tool call.
When the search is selected, the gateway preserves provider usage data and applies the request's allowed or blocked domain filter before it streams the local result. Domain rules match a host or one of its subdomains. Multiple tool calls, unexpected tools, malformed arguments, and empty queries are protocol failures.
This diagram shows how a Messages request becomes either a replayed provider stream or a local streamed web-tool result.
flowchart TD
A[Messages request] --> B{Supported web-tool shape?}
B -- No --> C[Reject unsupported request]
B -- Forced search or fetch --> D[Build local tool input]
B -- Automatic search --> E[Ask provider to choose]
E -- No tool call --> F[Replay provider stream]
E -- Valid search call --> G[Apply domain filter]
D --> H[Validate fetch egress when needed]
G --> I[Run outbound search]
H --> J[Run outbound fetch]
I --> K[Stream Anthropic tool result]
J --> K
References: src/…/service.py• L74-225 src/…/service.py• L228-277
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the client address, request host, and origin checks aligned when adding an administrative page or API. A route added under
/adminmust also receive the no-store policy. - Keep the versioned asset links in index.html aligned with the asset allowlist. New settings, integration, or Code session assets need both a link and an allowed filename. Shared browser controls must remain available before the scripts that use them.
- Keep custom provider fields, mutation actions, model-list key choices, and provider cards aligned. A provider can be created or changed without using the fixed provider catalog.
- Keep provider catalog logo filenames aligned with the provider cards and packaged asset list. Keep the source and license records with any new provider mark.
- Keep integration status routes aligned with the files that each connect or disconnect action changes. The UI message must state when the external client needs a reload, restart, reopen, or new chat. DSH Desktop changes must also state how existing sessions are affected.
- Keep VS Code Chat integration status and model-group changes separate from the selected model settings. A disconnect must remove only the integration's managed data.
- Keep integration startup state aligned with the status polling and with each client's connect or disconnect result. A completed desktop-app, editor, or DSH change must not leave the UI in a stale busy state.
- Keep local provider status polling aligned with the per-provider route contract. Each request must name one supported local provider, and an unknown provider must remain a not-found result.
- Keep the shared session layout and UI contracts aligned with the Code session view. A change to model controls, composer events, transcript behavior, or responsive sizing can affect the session flow together.
- Keep Code session epoch, version, and event-feed synchronization aligned with run, item, and prompt updates. A reconnect must not submit a saved command to an old session state.
- Keep Code session catalog generation and revision checks aligned with event-feed synchronization. A newer browser state must not be replaced by an older bootstrap or catalog response.
- Keep Code session prompt forms aligned with the server's supported approval, permission, question, URL, and tool-input contracts. An unsupported prompt must remain safe to decline.
- Keep the folder picker and manual path entry aligned with session creation. A selected path must remain distinct from the displayed text when the path contains line breaks.
- Keep catalog view names, model capability fields, and client launcher expectations aligned when changing model metadata or model discovery.
- Keep optimization detection and its setting flags aligned. A shortcut that changes its request shape can silently stop matching and increase provider traffic.
- Keep accepted server-tool definitions aligned with the emitted SSE result block types. Changes to fetch egress rules must also preserve redirect validation and address pinning.
- Keep automatic-search domain filtering aligned with the provider decision contract. The provider must still receive one hidden query tool and the client must still receive one valid result stream.
- Keep provider discovery error details aligned between the startup status response and the provider card. A saved but unverified credential must remain distinct from a credential that was rejected.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| An admin request comes from a non-loopback client, host, or origin | The page or admin API returns 403 | Require local values for all three parts of the request boundary |
| An admin response is cached | The operator can see stale settings, account state, integration state, or session state | Apply Cache-Control: no-store in middleware, error handling, and browser fetches |
| An asset URL uses an old version or a filename outside the allowlist | The browser cannot load the admin view or receives a missing-asset error | Change the asset allowlist and versioned page links together |
| A custom provider mutation or key list is out of sync with the provider catalog | The provider cannot be saved, selected, or authenticated as expected | Keep custom-provider fields, credentials, model references, and catalog options in one contract |
| An integration change completes but the external editor or app is not reloaded, restarted, or reopened | The client continues to use its old gateway settings | Show the client-specific follow-up action and keep integration status refreshable |
| A Code session feed has an old epoch or a gap in its event state | The Code view stops treating the session as ready and reconnects | Match feed, session, run, item, and prompt data to the current epoch and version |
| A Code session command is saved in the tab while the connection is lost | The command waits for synchronization or becomes an explicit retry instead of silently running twice | Keep one pending operation ID and deliver it only after the current feed is synchronized |
| A client expects one aggregate local-provider status response | Local reachability results are missing or cannot be matched to the requested provider | Request /admin/api/providers/{provider_id}/local-status for each supported provider |
| A provider refresh fails | Existing configured or cached models remain available, but the failed provider is reported | Return failed_providers and keep the combined catalog usable |
| A background discovery error has no visible provider detail | The operator cannot tell why a provider has no current models | Show the provider error from startup status and keep the generic fallback message |
| A credential is saved but cannot be verified | The operator may mistake a warning for a rejected save or replace a valid saved key | State that the key was saved and show the verification warning separately |
| A fetch URL uses a disallowed scheme or resolves to a non-public address | The fetch produces an unavailable tool result | Validate the scheme, host, and resolved addresses before connecting |
| A request mixes server tools or asks for unsupported automatic fetch | The Messages request is rejected as invalid | Accept only the supported forced or automatic request shapes |
| Automatic search returns multiple tools or malformed query input | The automatic flow returns an upstream protocol failure | Require one hidden search tool with one non-empty query field |
| Search or fetch times out, returns an HTTP error, or exceeds a size or redirect limit | The client receives an unavailable result instead of page data | Use bounded outbound work and emit a safe error result |
Key files
| File | Why to read it |
|---|---|
| src/…/admin_routes.py | Defines the local admin page, versioned assets, configuration, provider, integration, and model API contract. |
| src/…/admin_security.py | Defines the loopback boundary for the admin page, request host, and browser origin. |
| src/…/admin_cache.py | Defines the no-store rule for the full admin path. |
| src/…/index.html | Shows the high-level admin views, integration choices, and browser entry points. |
| src/…/admin.js | Shows how the UI loads configuration, applies changes, tracks startup, manages custom providers, connects integrations, and refreshes models and provider state. |
| src/…/admin.css | Shows the responsive admin shell, provider and settings panels, and the shared settings action area. |
| src/…/session_ui.js | Shows the shared Code session controls. |
| src/…/code_sessions.js | Shows the Code session library, catalog readiness, event synchronization, run and tool history, prompt handling, and reconnect flow. |
| src/…/routes.py | Defines the public model catalog routes and their client views. |
| src/…/model_catalog.py | Explains how configured and discovered models become client-facing records. |
| src/…/model_cache.py | Explains why model discovery can serve later catalog requests quickly. |
| src/…/optimization_handlers.py | Defines the supported local fast paths for Messages utility requests. |
| src/…/messages.py | Shows where web tools and optimizations join the main Messages lifecycle. |
| src/…/request.py | Defines supported Anthropic server-tool request shapes and automatic-search validation. |
| src/…/service.py | Coordinates provider choice, outbound execution, domain filtering, and local SSE results. |
| src/…/egress.py | Defines the safety boundary for user-controlled fetch URLs. |
| src/…/client.py | Defines the bounded outbound search and fetch behavior. |
| src/…/server_tool_sse.py | Defines the Anthropic SSE result flow for local tools. |