Skip to main content
The dashboard and approval UI are supported product surfaces. The JSON API response shapes and Web Push delivery contract remain experimental and may change without migration while those integrations mature.
agentuse serve includes an operations dashboard for the agents loaded from your served projects:
Open http://127.0.0.1:12233. The Home page streams:
  • agents running now, with recent output tickers
  • sessions waiting for approval
  • failed or verification-failed runs that need review
  • recent outcomes and upcoming schedules
  • deterministic metrics written through record_metric
Pending approval groups are ordered by their newest request, with newest gates first inside each group. Requests without a timestamp follow timestamped work. When the cached npm latest version is newer than the installed version, Home also shows a dismissible update banner. Its copy action uses the package manager that installed AgentUse. Dismissal is stored in that browser for that version, so a later release can appear normally. Mock and test sessions are excluded by default from all of these list-backed surfaces, and they never fire push notifications, so validating an agent does not distort the picture of what production is doing. They are still stored in full and remain inspectable: a mock session’s page is reachable by id at any time, and the sessions list can show them on request. Sessions, Agents, Approvals, Schedules, Stores, and Dashboard preferences remain directly addressable routes. A session page is the durable record for one run: its activity, approval gate, tool output, result, metrics, verification verdict, and follow-up controls stay together. Press Command+Shift+C on macOS or Ctrl+Shift+C elsewhere to copy a shareable link to the current dashboard route. A confirmation appears after the URL is copied. From a completed, failed, or approval-paused session, Revise agent file starts a visible internal session that diagnoses the run and proposes a validated change for operator review. An agent that has never run can start the same workflow from its detail page, using the agent file as the starting evidence. The agent detail hub keeps the resulting history in its Revisions tab. See Agent Revisions for apply, request-changes, discard, stale-source, and restore behavior. Settings can add an existing project or create a managed one, and can disconnect a project without deleting its files. For an existing project, guided discovery scans a sanitized, read-only view, accounts for agents already present, and proposes evidence-backed recurring work. Agent creation runs as a visible session, and any proposed schedule starts paused until you test and enable it. The agent and Schedules pages show declared cron expressions and deployment-local paused state. Pause or resume a schedule there, or with agentuse schedules pause and agentuse schedules resume, without editing agent frontmatter. Choose Run with custom from an agent or session action menu to supply a one-off instruction, select a different configured model, or do both. Leaving the model unchanged preserves the model declared by the agent. Provider setup in Settings supports Anthropic and OpenAI login or API keys, OpenRouter and OpenCode Go keys, plus custom OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages endpoints.

​
Viewer preferences

Dashboard preferences are local to the current Dashboard. In a browser they are saved in that browser only; in AgentUse for Mac they are saved in the Dashboard on that Mac. They do not change agents or server configuration.
  • Home sections and metric tiles can be hidden and reordered
  • Results can use 1, 7, 14, or 30-day windows
  • Metric tiles can render as a number, bars, or line chart
  • Agents can use cards, tables, metadata columns, grouping, and filters
  • Sessions can use list or feed views and combine status, agent, trigger, triage, and time-window filters
  • Sessions can set a “mock runs” filter to hidden (the default), shown, or only mock
Preferences are stored in localStorage and synchronize between tabs through browser storage events. Clearing site data resets them.

​
Install as a web app

The dashboard ships a manifest, home-screen icons, self-hosted fonts, and a cache-first service worker.
  • iPhone/iPad: open the dashboard in Safari, use Share → Add to Home Screen, then launch the installed app
  • Android/desktop Chromium: use the browser’s Install action when offered
The manifest and icons are available before operator authentication so a token-only session link can still be installed. Cached static assets make repeat loads fast and tolerate a temporary network outage; live data and actions still require the daemon. If a browser deployment leaves a stale cached bundle after an update, open Dashboard preferences and use Clear cached files & reload. The service worker activates updates on the next open, and stale chunk failures trigger one controlled reload automatically.

​
Web Push notifications

Notification bells on Approvals, Sessions, and Dashboard preferences control two independent categories:
  • approval requests
  • session completions and failures
The first enable action registers the service worker, requests browser permission, creates a push subscription, and stores that subscription in the daemon. Later toggles update only the category preference. Turning off the last category removes the server record and unsubscribes the browser. Subscriptions and VAPID keys persist under the AgentUse XDG data directory. Endpoints reported gone by the push provider are removed automatically. Push delivery is best-effort; the dashboard and session log remain the source of truth.
iOS Web Push works only from an installed Home Screen app. A normal Safari tab shows installation guidance instead of requesting a permission it cannot use.
If permission is denied, AgentUse cannot reopen the browser prompt. Re-enable notifications in the browser or operating-system site settings, then return to Dashboard preferences. Approval pushes carry the current pending count as an app badge. The dashboard resynchronizes the badge when the approvals list changes or a reviewer decides a gate, correcting any race between the run and the push. Notification taps open the associated session:
  • a warm installed app focuses an existing matching session window when possible
  • a cold iOS launch uses Declarative Web Push navigation and a short-lived cached target so the app can recover the requested session
  • the cached cold-launch target expires after two minutes

​
Live updates and recovery

The dashboard uses Server-Sent Events for live session and list updates. When a mobile tab returns to the foreground it reconnects automatically. An immediate HTTP status fetch paints a session before the event stream catches up, so a buffered or remote connection does not leave the page on an indefinite loading state. Long-running bash calls publish a bounded recent stdout/stderr tail after about two seconds. This preview is for people only: it is not added to model context, is removed when the call settles, and does not replace the final durable output.

​
Security and deployment

Local loopback deployments are open by default. Exposed hosts require AGENTUSE_API_KEY unless auth is explicitly disabled. Session capability links carry a token scoped to one session; operator pages and APIs still require the operator credential. For client-facing or demo deployments:
See Configuration Files for these keys, Approval Gates for review behavior, and Self-Hosting for reverse-proxy deployment.