Using the console
The console is served by the gateway itself (the Open Agent API service running on your machine, by default at http://127.0.0.1:8787), and the macOS desktop app embeds the same console. All data is read with the permissions of the current API key (the owner and the agents it may access), and reading statistics and timelines never calls any model or tool.
For endpoint details, field definitions and limits, see the sections Observable kernel: run timeline, activity pulse, queueing and capability negotiation and Console overview: revision, ETag and event stream in the protocol document.
Overview: the run cockpit
From top to bottom:
- Needs attention: tasks waiting for your approval, and tasks that were interrupted or ended incomplete and need manual recovery. The count comes from
metrics.requires_actionof the overview; the list shows at most 3 of the most recent tasks. If a task waiting for approval is older than the latest 12 tasks, only the count is shown here, and "View on the Tasks page" opens the "Needs attention" filter. - Key metrics: the number of tasks in the statistics window (with a trend line), the success rate, the median duration (P50: half of the tasks finish within this time; with the P95 duration, meaning 95% of tasks finish within this time, and the sample count), and the tasks currently in progress (split into queued, running and awaiting approval; when tasks are waiting for the caller to run its own tools, it notes "N waiting for the caller": these count as running and not as awaiting approval, and the note is not shown when an older gateway does not provide it). The definition of the success rate is the one in the protocol document, and cancelled tasks do not count as failures.
- Activity statistics (called the "activity pulse" in the protocol document): tasks in the last 24 hours (one bar per hour) or 7 days (one bar per 6 hours), stacked by status: completed, in progress, cancelled, interrupted, failed. Intervals are aligned to UTC and displayed in local time; hover to see the details of an interval.
- Where the time went: the duration of up to the latest 100 finished tasks, attributed along each task's critical path (the chain that determines the total duration) to five categories: model reasoning, tool execution, queue wait, approval wait, and other. Parallel tool calls are not timed twice, so the items add up to the actual duration of the tasks. A one-line reading is given below; for example when queue wait reaches 25%, it suggests that execution capacity may be short.
- Agents: each agent's number of calls, success rate and median duration within the statistics window.
You can switch the statistics window at the top right of the activity statistics card, or set a default in "Settings › Preferences › Activity window".
Tasks and run details
- Task table (one call is one task): filter by status (All, Active, Needs attention, Completed, Failed). A queued task shows its position in the queue and the estimated time until it starts; for a running task whose current step is still waiting in an execution machine's queue (the machine is at capacity or the model is cooling down), it shows "Next step starts in about N seconds". The estimated time is an estimate based on recent execution durations, not a promise; the position counts only your own tasks. The duration of a running task keeps counting up locally.
- Run details › Timeline: shows the phases of a task in lanes. The main line is queueing, model reasoning and approval, and parallel tool calls each get their own lane; colors distinguish the phase types.
- The ones with a dark outline at the bottom are on the critical path.
- In-progress phases have flowing stripes; tool calls that hit the cache have diagonal stripes; steps whose outcome is unknown are marked with an orange dashed frame. Tasks completed before this version have no recorded model turns, so their model phases are estimated from the gaps between tool calls, marked with a gray dashed frame, and the caption notes "some model phases are estimates".
- A queue phase notes its reason: queued, yielding to waiting tasks (fair scheduling), re-queued after approval, switched to a fallback agent, or waiting for an execution machine. Hovering over a model phase shows the model route used (one of the models the agent may use, with its provider) and the number of retries; a subagent phase is clickable and opens its own task.
- A caller running its own tools (bridge, see harness.md) is its own segment, named "Caller tool", in the same color as tool phases.
- If one wait (approval, a caller running a tool, or queueing) takes more than 70% of the total duration and is more than 8 times the rest of the work, the timeline collapses that segment to a fixed width, marks its actual duration with stripes and ticks, and shows the rest at true scale.
- Below is this task's "Where the time went"; it is not shown when there is only one category (for example, still queued).
- Queue hints: a queued task shows its position, estimated start time and reason at the top of its details (waiting for an execution slot, fair scheduling yielding for now, re-queued after approval, execution machine busy, model cooling down); a running task whose current step is waiting in an execution machine's queue also shows the reason and the estimated wait.
- Approvals: operations awaiting approval sit at the very top of the details, and you can approve or deny them right there; denial, expiry or cancellation never grants execution. For an agent published with automatic approval, its permission requests are approved directly by policy, do not appear here, and do not enter "Needs attention"; every automatic approval is still recorded (the event
approval.resolved, withactor: "policy:auto"). - Automatic approval at publish time: when you choose "External agent" in the publish dialog there is a switch, "Approve its permission requests automatically", off by default, with a line below warning about the consequences of turning it on (it no longer waits for your approval before running commands or changing files, it can do what you could do by using the software directly on this computer, and it should be opened only to callers you trust). Once on, the agent card carries an "Auto-approve" mark whose tooltip explains it; in the agent details, the "Approvals" row of the access capabilities shows "Auto-approved (set at publish)".
- Waiting for the caller: when a task is parked on the caller's own tools (bridge mode), the details have a separate "Waiting for the caller" section saying "This task is waiting for the caller to run its own tools. It continues once the results are sent back.", and listing each pending call's tool name, an argument summary (expand it to see the full text) and the time remaining. These calls need nothing from you and do not appear under "Approvals"; when all pending actions are of this kind, the status at the top of the details shows "Waiting for the caller". If no result comes back by the deadline, the task ends with
client_tool_timeout. The task list and the recent tasks of the overview also show "Waiting for the caller" (they readwaiting_onof the list row); such tasks do not appear in the overview's "Needs attention" card and do not count toward the Tasks page's "Needs attention" filter, and the overview's awaiting-approval count does not include them either. An older gateway does not providewaiting_on, in which case they are still shown as awaiting approval. - Images and structured output: when a task came with images, its details have a section "This task came with N image(s)" with each image's name, size and a thumbnail (the thumbnail is read through the authenticated file download, so the key needs the
filespermission); an image given as a URL shows only its host ("read by the model provider"). When the request asked for structured output, the line next to the status and the model adds "structured output (json_schema)" (the kind isjson_object,json_anyorjson_schema) and, when the gateway had to ask the agent to correct its answer, "corrected N×". Image bytes never appear in the timeline or the logs. See images.md and structured-output.md. - Workbench (
#workbench): an interactive multi-turn chat and protocol debugging workspace in the sidebar. Choose any published agent, model route (auto,@fast,@best,@eco, or a concrete route, plus recommendation-only preview), shared project memory, and caller-tool boundary (auto/managed/bridge/reject); attach or paste images; inspect live reasoning progress, tool badges, and downloadable artifacts; approve or deny pending owner actions inline (waiting_on === "owner"), or submit mock results for bridged callertool_calls(waiting_on === "caller") to continue the same run viaprevious_response_id; and export ready-to-runcurl, OpenAI, Claude, and Gemini SDK snippets. - Endpoints › When the caller is an agent too: shown when the gateway supports
client-tools-policy-v1. It explains how the tools a caller brings along are handled, as a table of four modes:auto(the default, used when the request chooses none: the tools are bridged when the agent can take them over, otherwise things work as before),managed,bridgeandreject. It has a curl example carrying theX-OAA-Client-Tools: bridgerequest header, and notes that bridging supports built-in kernel agents, Codex, Claude Code, Antigravity ACP, and ACP external agents. See harness.md for details; the gateway settingclientTools.defaultchanges whatautostands for. - Endpoints › Webhooks: shown when the gateway supports
webhooks-v1and the key is an owner-wide admin key (the API refuses every other key). Provides full CRUD management for run-event callback endpoints alongsideoaa webhookand/v1/webhooks: add an endpoint (HTTPS URL, subscribed events, description, optionalinclude_output, displaying the signingsecretonce on creation), send a test ping, delete an endpoint with confirmation, and inspect recent delivery statuses, HTTP codes, and retry counts. See webhooks.md.
Developer platform (operators)
The "Developer platform" page under the "Connect" group lets operators list agents and set prices, manage developer accounts and balances, and generate redeem codes. It requires admin permission. For the endpoints see platform.md ("Endpoint overview"); all amounts shown on the page are in credits.
- When not enabled: when
GET /healthof the gateway has noplatform-v1feature, the page shows a single explanation page: what it is for (opening your agents to other people), when you do not need it, a comparison of the two ways to hand out access ("API keys" and the "Developer platform"), and an "Enable" button (fill in the site name, the registration mode and the credits given to new accounts). Settings are saved throughPUT /v1/platform/setupin the gateway's data and take effect after the gateway restarts; after saving and before restarting, the page says it takes effect after the restart (pending_restart). When the configuration file has aplatformsection (managed_by_config), the settings are read-only. No data area is shown, and no platform endpoints are read other thanGET/PUT /v1/platform/setup. - Summary: the number of developer accounts (active / disabled), the total balance, cumulative consumption and task count, plus the site name and registration mode (
closed,invite,open; change it in the gateway configuration, read-only here); the developer portal address (/portal/) can be copied at the top right. - Usage (between "Summary" and "Listings & pricing"): a switch at the right of the title, "Tasks / Spent", changes a bar chart of the last 30 days by day (dates in UTC, drawn the same way as "Recent activity" on the overview; hover over a bar to see that day's tasks, spend and tokens); the top right of the chart is the 30-day total. When there are no tasks in 30 days (or no spend, under "Spent"), the chart is replaced by one line of empty state. Below the chart are two small tables side by side: by agent (agent, tasks, tokens, spent) and by account (email, tasks, tokens, spent; the gateway returns at most the 50 accounts with the highest spend); clicking an email fills the search box in the top bar with that email, and the developer table then searches by email and scrolls to that section. The data is read from
GET /v1/platform/usage?days=30and follows this page's refresh rhythm. - Listings & pricing: the table lists the agent, title, price per task, price per 1,000 tokens and whether it is listed. "List an agent" chooses from agents that are published but not yet listed, and fills in the title, summary, tags and the two prices. The per-task price is held when a task starts, charged only if the task completes and released otherwise (0 means no per-task charge). An agent that does not report token usage (most external agents) can only be priced per task: the per-1k-tokens price must be 0, or saving is refused (
usage_pricing_unsupported). For an agent that runs with host authority (an external agent, or one with host tools) the dialog also has the switch Let platform accounts run this agent on this machine, off by default, with an explanation of what it means: platform accounts then run that one agent as the system user that runs the gateway, bounded by its approval policy (approvals are decided only by you), and a note when the agent's approval policy isauto. While it is off, platform accounts are refused (isolation_required) and the portal catalog does not show the agent. The listing table says where each one stands in its status column: "Listed", "Unlisted", "Agent removed" for a listing whose agent has been deleted, or "Accounts blocked" for a listed agent that accounts cannot call yet because it, or an agent it delegates to, still needs the switch (hover for which); a line under the title says "Accounts run it with host authority" when the switch is on. See platform.md. Rows can be edited in place, taken off the shelf or put back, or have their listing removed; taking off the shelf and removing need a second confirmation. - Developers: the table lists email, name, status, balance, key count, task count, cumulative spend and last activity, and uses "Load more" to page when there is a lot of data. The search box in the top bar searches the gateway by email. Row actions: adjust balance (add or deduct, a note is required, and the result cannot go below 0; an optional "External reference": the same reference is credited only once, which suits payment callbacks, and a repeated submission shows "This reference has already been credited; nothing was added twice." and adds no more credits), view the ledger (for lines with an external reference, the reference is shown in small text under the note), reset password, and disable / enable; disabling and resetting a password need a second confirmation. "Reset password" has two ways: generate a one-time reset code (default, recommended): the plaintext is shown only once on the result page, can be copied, and states its expiry time (valid for 24 hours; generating a new one invalidates the old one), and once you close the dialog the copy on the page is cleared; you send the reset code to the developer, who sets a new password themselves on the portal sign-in page, and you never learn their password; or set a new password directly (you set it for them, so you know the password). "New account" is not limited by the registration mode, and "Generate" can produce a random initial password.
- The key's "Top-up (billing)" permission: when you generate an API key and the gateway has the developer platform enabled, the permissions have one more item, "Top-up (billing)", which can only add credits to developer accounts and look accounts up by email, for payment callbacks; without the
platform-v1feature this item is not shown. It appears as "Top-up (billing)" in the key list. - Redeem codes: the table lists the kind (credit code, invite code), credits, used / available uses, expiry, note and status, and a row can be revoked (needs a second confirmation; credits already redeemed are not taken back). "Generate redeem codes" sets the kind, credits, number of uses, quantity (1 to 100), validity and note; the plaintext of the codes is shown only once on the result page after generation and can be copied as a batch, and once you close the dialog the copy on the page is cleared, so the gateway holds only hashes.
The data on this page is read only while the page is shown, refreshed about every 20 seconds or when you click the refresh button in the top bar, and refreshed immediately after every action; when a read fails, the existing data stays on screen and the reason is shown at the top of the page.
Live sync and compatibility
- When the gateway provides
/v1/overview/events, the top bar shows "Live", and changes are pushed to the console within about 250 ms; when it does not, the console polls at the interval you set. - Every change event carries a reason (
runs,catalog,nodes), and the console re-reads only the affected data. For example, a change in an execution machine's load does not re-read the activity statistics. All reads use ETag conditional requests: when the data has not changed, the gateway returns 304 with no body. - Capability negotiation: the console decides which features the gateway supports from
featuresinGET /health. When connected to an older gateway, the activity statistics, timeline and queue hints are hidden automatically, and everything else works as usual.
Settings
- Appearance: language (Chinese or English; on first open it follows the browser language, and after switching the page reloads, with the choice saved in localStorage under
oaa.console.lang; the macOS app's own menus and dialogs follow the system language instead, see below), theme (System, Light, Dark), dark palette (Black, Tide), density, motion and the sidebar. When the window width is between 901 and 1180 pixels, the sidebar automatically folds into a narrow icon rail (hover or focus an item with the keyboard to see its name, and the number of tasks in progress becomes a small dot on the icon corner); narrower than that, it becomes a bar above the page. "Collapse sidebar" still hides the sidebar entirely. - Preferences: default home page, data refresh interval, time display (relative or exact), activity window, default preference (the selection strategy for model routes), and the getting-started checklist.
- Connection: the key name, permissions, accessible agents and the gateway Base URL, with "Switch key", "Disconnect", and, for admin keys, "Manage API keys".
- Desktop app (in the unified cross-platform Electron desktop app across macOS, Windows, and Linux): Dock / tray badges, approval notifications, launch at login, showing the data folder, opening in the browser, copying the admin key, and restarting the gateway.
- Keyboard shortcuts:
⌘Kcommand palette,⌘,settings,⌘\toggle the sidebar,/focus the search box,⌘↵run the task in the agent sheet,Escclose a sheet or dialog. On Windows and Linux,⌘becomesCtrl.
Preferences are saved only in the local browser (localStorage oaa.prefs.v1) and are never uploaded to the gateway.
The unified desktop app (macOS, Windows, and Linux)
- Native window: on macOS there is no title-bar strip at the top (
hiddenInsetwith traffic lights at{ x: 20, y: 18 }); the red, yellow and green buttons sit at the top of the sidebar, on the same row as the sidebar toggle, the page path and the search box. Double-clicking the empty title area zooms or minimizes the window according to your system setting. Windows and Linux use the same sandboxed Electron shell (nodeIntegration: false,contextIsolation: true,sandbox: true). - Dock badge, system tray quick approvals, and launch at login: macOS Dock and the system tray show the live count of tasks waiting for owner approval. Clicking the menu-bar / system-tray icon opens the sandboxed Tray Quick Panel showing gateway health/port, active run count, pending owner approvals with one-click Approve / Deny actions (
/v1/runs/{id}/actions/{actionId}), and a Launch at Login toggle (automatically disabled in isolated--oaa-data-dir/OAA_DESKTOP_HOMEruns). - Approval notifications: off by default. The first time you turn them on, macOS asks whether to allow notifications; afterwards you can use "Send test notification" to confirm the permission. No notification pops up while the console window is in front. A notification contains only the agent name and no task content, because notifications may appear on the lock screen. Clicking a notification opens the matching task.
- First launch: the app publishes the offline sample agent, switches on the agent engines it finds on the Mac, and shows a dialog once that says exactly that and where to turn an engine off (this page's "Execution machines"). Details in install.md.
- Language: the app's own menus, dialogs and notices follow the system language (Chinese when your first preferred language starts with
zh, English otherwise), the same rule the console and the command line use. The console inside the window keeps its own language choice (Settings; theoaa.console.langentry in the page's local storage); the app never writes it, so a console that has not been switched follows the browser language as before. - Closing the window does not stop the gateway: the gateway keeps running in the menu bar; from the menu bar icon you can reopen the console or quit the app.
Privacy and security
- Statistics and timelines read only persisted run events; they call no model or tool and add nothing to storage.
- A timeline contains only phase types, times and machine-readable identifiers (such as tool names and step IDs), and never task input, tool arguments or output content; that content is read only when you expand the matching step or download it.
- The console page follows a strict content security policy (CSP): no third-party scripts, no inline scripts or inline styles, and keys never appear in the URL.