Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / api-admin-and-web-tools

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 /admin must 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

TriggerConsequenceGuard
An admin request comes from a non-loopback client, host, or originThe page or admin API returns 403Require local values for all three parts of the request boundary
An admin response is cachedThe operator can see stale settings, account state, integration state, or session stateApply Cache-Control: no-store in middleware, error handling, and browser fetches
An asset URL uses an old version or a filename outside the allowlistThe browser cannot load the admin view or receives a missing-asset errorChange the asset allowlist and versioned page links together
A custom provider mutation or key list is out of sync with the provider catalogThe provider cannot be saved, selected, or authenticated as expectedKeep 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 reopenedThe client continues to use its old gateway settingsShow 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 stateThe Code view stops treating the session as ready and reconnectsMatch 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 lostThe command waits for synchronization or becomes an explicit retry instead of silently running twiceKeep one pending operation ID and deliver it only after the current feed is synchronized
A client expects one aggregate local-provider status responseLocal reachability results are missing or cannot be matched to the requested providerRequest /admin/api/providers/{provider_id}/local-status for each supported provider
A provider refresh failsExisting configured or cached models remain available, but the failed provider is reportedReturn failed_providers and keep the combined catalog usable
A background discovery error has no visible provider detailThe operator cannot tell why a provider has no current modelsShow the provider error from startup status and keep the generic fallback message
A credential is saved but cannot be verifiedThe operator may mistake a warning for a rejected save or replace a valid saved keyState that the key was saved and show the verification warning separately
A fetch URL uses a disallowed scheme or resolves to a non-public addressThe fetch produces an unavailable tool resultValidate the scheme, host, and resolved addresses before connecting
A request mixes server tools or asks for unsupported automatic fetchThe Messages request is rejected as invalidAccept only the supported forced or automatic request shapes
Automatic search returns multiple tools or malformed query inputThe automatic flow returns an upstream protocol failureRequire 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 limitThe client receives an unavailable result instead of page dataUse bounded outbound work and emit a safe error result

Key files

FileWhy to read it
src/…/admin_routes.pyDefines the local admin page, versioned assets, configuration, provider, integration, and model API contract.
src/…/admin_security.pyDefines the loopback boundary for the admin page, request host, and browser origin.
src/…/admin_cache.pyDefines the no-store rule for the full admin path.
src/…/index.htmlShows the high-level admin views, integration choices, and browser entry points.
src/…/admin.jsShows how the UI loads configuration, applies changes, tracks startup, manages custom providers, connects integrations, and refreshes models and provider state.
src/…/admin.cssShows the responsive admin shell, provider and settings panels, and the shared settings action area.
src/…/session_ui.jsShows the shared Code session controls.
src/…/code_sessions.jsShows the Code session library, catalog readiness, event synchronization, run and tool history, prompt handling, and reconnect flow.
src/…/routes.pyDefines the public model catalog routes and their client views.
src/…/model_catalog.pyExplains how configured and discovered models become client-facing records.
src/…/model_cache.pyExplains why model discovery can serve later catalog requests quickly.
src/…/optimization_handlers.pyDefines the supported local fast paths for Messages utility requests.
src/…/messages.pyShows where web tools and optimizations join the main Messages lifecycle.
src/…/request.pyDefines supported Anthropic server-tool request shapes and automatic-search validation.
src/…/service.pyCoordinates provider choice, outbound execution, domain filtering, and local SSE results.
src/…/egress.pyDefines the safety boundary for user-controlled fetch URLs.
src/…/client.pyDefines the bounded outbound search and fetch behavior.
src/…/server_tool_sse.pyDefines the Anthropic SSE result flow for local tools.