Skip to content

Latest commit

 

History

History
266 lines (199 loc) · 20.1 KB

agent-native-admin.md

File metadata and controls

266 lines (199 loc) · 20.1 KB

Agent native admin UI

Native browser access defaults to disabled. OCC proxies HTTP/WebSocket chat or administration using OCE sessions and exact-Agent permissions. Gateway managed mode limits administration.

Host-only session exchange

For guarded OIDC, select agentNativeAdmin.sessionMode: host-only-exchange (OCC_AGENT_NATIVE_ADMIN_SESSION_MODE=host-only-exchange) and omit agentNativeAdmin.sharedCookieDomain and OCC_AUTH_COOKIE_DOMAIN. Console and Agent origins must use same-site HTTPS and route to OCC. Launch creates no account or grant.

Opening the Agent creates a 60-second, window-bound challenge, confirmed through the same Console session. One-use redemption sets a Secure, HttpOnly, SameSite=Strict host-only cookie, expiring with its parent session (at most eight hours). HTTP, WebSocket admission and renewal recheck the session, Principal, Agent, Namespace, revision and authorization. Neither cookie reaches the Gateway.

Repeating Open Agent UI reuses a valid handle with the same authority and expiry, preserving WebSockets. Otherwise, redemption issues a new handle. A version-change refusal on an eligible HTML navigation shows HTTP 403 Agent version changed with a Console return link. It never redirects or transfers access.

Who can open it

Console access requires a human session and exact-Agent operate or administer. operate grants chat access; administer retains administration access and takes precedence when both are granted. Agent read alone and service API keys grant neither mode.

Password and OIDC sign-in support native browser access with shared cookies. OIDC also supports the host-only session exchange. Google sign-in does not support native browser access.

Enable during creation

In Create Agent, select Enable browser chat. Unchecked by default, it requires Installation native access enablement and compatible gateway support. Ordinary Agent owners can use this option without Installation administration.

API callers set nativeAdmin: true on POST /namespaces/:namespaceId/agents and supply expectedConfigurationGeneration. In addition to ordinary Agent creation permissions, this requires update on the selected Configuration, which must not be referenced by any Agent. OCC checks the generation, prepares the Configuration, and creates the Agent atomically. Deploy normally afterward.

Supported guided provisioning accepts nativeAdmin: true on POST /namespaces/:namespaceId/agents/provision and prepares the initial Configuration before queueing its deployment. Its existing provisioning permissions still apply.

Both paths save controlUi.enabled, the exact derived HTTPS origin (including its port), gateway.publicOrigin, and the trusted-proxy machine policy in the initial Configuration. It preserves existing allowed origins, Secret bindings, and unrelated settings. Conflicting authentication modes, unsupported auth fields, disabled device authentication, and host-header origin fallback are refused. Guided-provisioning retries retain the Agent identity and prepared Configuration. Browser preparation does not change the creator's Agent permissions.

Native domain recovery.

Requirements

  • agentNativeAdmin.enabled: true in Helm, which sets OCC_AGENT_NATIVE_ADMIN_ENABLED=true on the API.
  • agentNativeAdmin.domain set to the Agent host suffix, such as agents.oce.example.com, without scheme, wildcard, port, or path. Helm passes it as OCC_AGENT_NATIVE_ADMIN_DOMAIN. Use a previously unused DNS suffix for the first pilot rollout; the proxy blocks new service-worker registration but does not evict service workers that a prior experiment registered on the same origin.
  • HTTPS Console and Agent DNS hosts that share a non-public suffix. In shared-cookie mode OCC derives the cookie domain automatically; see shared sessions. The Agent suffix is required even when browser access is disabled.
  • Private gateway routing (enabled by default). Prepare its prerequisites and Envoy routing before installation. Helm rejects native admin when routing is disabled; the API needs each Agent's private route.
  • OCC_AUTH_BASE_URL set to the public OCC origin that serves the console, for example https://console.oce.example.com.
  • The Agent must be running with a selected version owned by the selected Compute Driver: both Driver ID and implementation must match. The browser transport must map from private wss: to private https:.
  • The native Configuration must retain the machine's occ-workspace-files identity and operator.admin grant, enable controlUi, and allow the exact Agent origin. The support check rejects token auth, disabled device authentication, and host-header origin fallback. Browser access neither requires nor creates device auto-approval.
  • A qualified runtime must support delegated profiles and enforce the scope ceiling. Chat also requires x-openclaw-scopes in saved trustedProxy.requiredHeaders; preserve other required headers.

Local development uses the existing loopback HTTPS proxy for Console sessions in Compose and Kubernetes-only profiles. Compose with Kubernetes Compute and OpenShell also enables native Agent routing. The first-Agent helper’s --control-ui option supplies the Agent’s native configuration.

Authorization and availability

GET /namespaces/:namespaceId/agents/:agentId/native-admin requires a human session, exact Agent existence, and either operate or administer. OCC checks this boundary before returning any feature status, including disabled. Successful access selects mode: "chat" or mode: "admin"; unsupported narrow runtime authority fails closed instead of granting administration.

Status Meaning
disabled The Installation has not enabled native admin UI access.
stopped The Agent is not in desired running state.
unsupported See unsupported reasons.
unavailable The running Agent has no selected version, or an exclusive replacement prevents access.
available The caller may open the returned url for the selected version.

During a newer exclusive replacement, OCC rechecks access to the selected predecessor. Its saved replacement record must name that predecessor and have phase pre-stop. OCC returns unavailable after the worker records stopping or if no record matches the selected predecessor.

A stopped Agent without a selected version returns only status: "stopped", including before first deployment and after stop reconciliation. While the Agent is stopping, a chat operator also receives only the status. An administrator with a selected stopped version receives target fields. Dependency outages, including IAM, return 503 DEPENDENCY_UNAVAILABLE. Malformed requests, IAM denials and missing sessions use the protected-route error envelope.

After lifecycle and native configuration checks, OCC compares the selected Compute Driver's ID and implementation with the version's recorded owner. A mismatch returns 503 DEPENDENCY_UNAVAILABLE from the status API and 403 from Agent-host HTTP. WebSocket admission closes the socket without an HTTP response. These refusals precede endpoint lookup, gateway-key lookup and connection. A mismatch during lease renewal closes the connection.

Changing the selected Compute Driver leaves existing versions in place. Each API process logs one native_admin.compute_owner_mismatch per version and selected Driver, naming both IDs and implementations. Select the version's Compute Driver again to restore access.

Without a valid session, / or /chat/main[/<session>] navigations can return to the Console. Session segments accept letters, digits, hyphens and underscores; trailing slashes are allowed. Only the opaque host key survives; paths and queries are dropped. Responses use Cache-Control: no-store and Referrer-Policy: no-referrer, without checking Agent existence.

Only a user-activated (Sec-Fetch-User: ?1) top-level HTML navigation is redirected. The same page load without that header, including every Safari navigation, stays HTTP 403 with one Sign in link to that console URL. Link previews, API requests, and WebSocket upgrades send no navigation Fetch Metadata and keep their ordinary refusal.

Native HTTP admission returns 503 DEPENDENCY_UNAVAILABLE on session-store failure, timeout, failed denial audit or, for an authorized caller, a deployment in progress or no Gateway answer, so the Agent UI reconnects. Stopped and unsupported Agents return 403. An authorized caller's eligible navigation shows Agent unavailable, or Agent not responding (Gateway silent), with a Console link. Callers without access get the same 403 in every state; refused WebSocket upgrades close.

The Console’s authenticated GET /native-admin/return/<key> operation checks exact Agent operate or administer access and returns the Namespace and Agent IDs even if the Agent is stopped. Unknown and unauthorized keys receive the same 404. Recovery ends at Agent detail; opening native chat is a separate action.

A signed-in person who has neither chat nor administration access to the Agent is never redirected. Their top-level HTML navigation stays HTTP 403 on a page that does not name the Agent; its only link, Go to your Agents, points at /console/agents.

If a failed reconnect's health probe and Control UI configuration get 401 or 403, the Control UI shows Sign in to continue loading content, an access check, not proof of expiry. Sign in opens / in a new tab, then offers Check again. After Not now the prompt stays closed; the tab reconnects and recovers after a sign-in elsewhere or a reload, which drops the draft.

Unsupported reasons

  • not-enabled means the Configuration did not opt this Agent into browser chat. Control UI is off, or it is on with neither the Agent origin nor trusted-proxy auth.
  • configuration means another native setting prevents access.
  • compute means the selected Compute Driver supplied no valid private wss: endpoint.

Agent host identity

OCC derives a stable browser host from the Installation ID, Namespace ID, Agent ID, and configured agentNativeAdmin.domain. The hostname is opaque and must not be reused for another Agent identity. The derived host is separate from the console origin, which gives each Agent UI its own browser origin.

An Agent URL uses the derived host directly:

https://agent-<opaque-hash>.<agentNativeAdmin.domain>/

Admission resolves the irreversible host hash through platform state without a separate registry or cache. Unknown hosts, wrong suffixes, deleted Agents and ambiguous matches fail closed.

Workspace-file access uses the Compute Driver's getGatewayEndpoint, typically:

wss://<private-host>/namespaces/<namespaceId>/agents/<agentId>

Both browser modes use optional getGatewayBrowserRequest. It returns a private endpoint and trusted headers for the server-resolved Installation, Principal, and mode. Missing support returns unsupported; OCC never falls back to the machine endpoint. Kubernetes uses /native-browser/ on the existing managed HTTPRoute and a separate credential for each revision.

OCC maps browser requests to the endpoint's HTTPS authority and path; WebSocket upgrades also pass through OCC. Workspace files retain WSS. The proxy blocks service-worker script requests and adds CSP worker-src 'none' to prevent service-worker registration.

Shared session boundary

Shared-cookie mode uses the automatically derived domain. Every host receiving that cookie must be a trusted OCE ingress endpoint. Agent hosts route to OCC, not Envoy or tenant Services. OCC strips cookies, Authorization, API keys, forwarded identity/scope headers and native Set-Cookie; the Gateway never receives the OCE cookie.

Native chat or other activity in the Agent tab does not renew the console session. Session expiry, logout, session revocation, permission removal or a change between chat and administration authority, pilot disablement, Agent unavailability, or a version change closes active WebSockets during the authorization lease. A socket remains bound to the session that opened it; replacing a browser cookie does not replace that socket’s session. Reconnecting uses the same stable Agent host and the selected version when the shared OCE session, exact Agent permission, and native configuration remain valid.

Gateway managed mode

Managed mode defaults on where the Compute Driver supports it. It prevents Gateway administrators from editing native configuration, opening Gateway-local terminals, and running Gateway-hosted command jobs. An Installation administrator can change the setting in OCE for the next deployment. See Gateway managed mode for runtime requirements and behavior when managed mode is off.

Native authority and drift

Each OCE Principal receives a Gateway-local native profile, independent of email or provider. Attached sign-in methods, reconnects, regrants, and redeployment reuse it while native storage is retained. No OCE account-linking API or database table is added.

OCC delegates operator.admin for administer, or operator.sessions.write for operate. The latter permits conversation operations and implies session read. Delegated scopes are both grant and ceiling; native roles and session rules can narrow them. Browser headers, static identity grants, and device grants cannot widen them. Delegated access issues no reusable device token. OCC audits Principal, Agent, mode, and details.nativeAdmin.subject; native sessions retain creator/sender attribution.

The internal binding is not a user-editable alias: attach sign-in methods in OCE. Native aliases and merges cannot combine OCE Principals. Profiles do not isolate tools, credentials, files, or execution.

Chat access does not grant native configuration writes, device or pairing administration, approval management, or elevated gateway commands. A runtime must support delegated authentication before either browser mode is enabled.

With Gateway managed mode off, native changes stay in gateway-local state. Kubernetes reloads the managed snapshot on Pod recreation or redeployment. Save lasting settings in the OCE Configuration. See Kubernetes managed native configuration for mounts and copy behavior.

Do not change gateway.bind, gateway.customBindHost, or gateway.tailscale.mode in that copy. OCE checks these listener settings in the managed Configuration at deployment, not after a native edit. The edit survives same-Pod restarts. With loopback, the Gateway stays Ready, because its readiness check uses loopback, but refuses traffic to the Pod IP: the native admin UI goes dark and cannot undo the edit. With Tailscale serve or funnel and the rendered lan bind, native startup fails and the container restarts in a loop. To recover, delete the Pod or redeploy the Agent.

Redeployment does not imply a factory reset of native files, conversations, device state, plugins, or other persistent gateway data.

Failure behavior

  • Helm requires HTTPS and an Agent DNS suffix even when native access is disabled. Native access also requires private gateway routing.
  • Auth setup rejects missing or incompatible Console and Agent DNS hosts, public-suffix cookie scope, and short auth secrets. The removed sharedCookieDomain and OCC_AUTH_COOKIE_DOMAIN inputs are rejected, including empty values.
  • Native access setup rejects invalid enablement, origins, or transport prerequisites. A missing OCC_GATEWAY_API_KEY_PATH reports GATEWAY_API_KEY_UNAVAILABLE.
  • Host-only exchange requires guarded OIDC sign-in, same-site HTTPS Console and Agent origins, and disabled sandbox preview.
  • See unsupported reasons for native configuration and private gateway endpoint refusals.
  • The console hides native access for disabled and denied states and explains stopped, unsupported, or unavailable states. When available, Open chat or Open Agent UI opens a new tab directly in shared-cookie mode or completes the host-only exchange.
  • Attributable IAM denials remain audit events for status checks, native-host proxy admission, and recurring WebSocket lease renewal. Those denial paths preserve the human IAM principal and exact Agent target.
  • Proxied HTTP and WebSocket requests strip browser credentials, service keys, forwarded headers, native identity/scope headers, and native Set-Cookie before responding through OCC. WebSocket upgrades require a non-null exact Agent Origin; accepted 101 connections audit websocket.connect with connectionId and websocket.close with the same connectionId plus closeReason, refresh authorization every 25 seconds, close when a lease check fails or takes more than 5 seconds, set closeReason to distinguish lifecycle, revocation, dependency, client, upstream, and shutdown paths, and are destroyed during API preClose.

Related

Manual Notes

[keep this for the user to add notes. do not change between edits]

Changelog

  • 2026-11-03: Documented the unactivated sign-in page.

  • 2026-10-14 01:20: Documented the Compute-owner mismatch warning and how to restore access. (fix-1287)

  • 2026-10-14 00:10: Distinguished HTTP refusal from WebSocket socket closure without a response. (01a13783-3cb5-7f53-8668-b2e3affa2b12 - e64d04f12cb80eb438a4c442180e56c2a2adae38)

  • 2026-10-13 23:57: Documented native-admin refusal when selected Compute ownership differs from the selected version. (01a13783-3cb5-7f53-8668-b2e3affa2b12 - e64d04f12cb80eb438a4c442180e56c2a2adae38)

  • 2026-10-10 09:20: Documented that native listener edits are not re-checked and how to recover. (docs-1014)

  • 2026-10-06 12:00: Documented the Compose/OpenShell development endpoint and first-Agent Control UI option.

  • 2026-09-21 21:20: Documented status-only stopped results before deployment and after stop reconciliation. (01a0c750-0c10-7492-97eb-f4124cded820 - 156dd67b7bd280a380d96b5c34a64e402fe3b96b)

  • 2026-09-20 08:21: Linked Kubernetes configuration-copy details to the implementation reference after the Driver documentation refactor. (01a0b7fd-13fa-7dc2-8653-5c5814b59305 - f4e22e48)

  • 2026-09-20 08:53: Replaced the temporary exchange launch description with the shared OCE session cookie model, cookie-domain trust boundary, host-to-Agent admission, and current-version reconnect behavior. (cody/01a0b7fd-13fa-7dc2-8653-5c5814b59305 - 5e5f12f37842ae7239d73432e00609547627ded8)

  • 2026-09-19 22:27: Documented exact-Agent disabled-status gating, IAM denial audit preservation, and WebSocket connectionId/closeReason audit fields. (01a0b7fd-13fa-7dc2-8653-5c5814b59305 - 9621ce4e)

  • 2026-09-19 21:14: Documented gateway-routing Helm validation, service-worker domain setup, and the explicit native-admin writable-config predicate. (01a0b7fd-13fa-7dc2-8653-5c5814b59305 - 06c23b9c)

  • 2026-09-19 21:07: Documented the unavailable availability success state and separated it from protected-route error envelopes. (01a0b7fd-13fa-7dc2-8653-5c5814b59305 - 06c23b9c)

  • 2026-09-19 20:19: Added the current native admin UI reference for enablement, authorization, routing reuse, and source-confirmed launch status behavior. (01a0b7fd-13fa-7dc2-8653-5c5814b59305 - 06c23b9c)