Overview

In holaOS, an app grant routes requests to a bound external account but does not make every action safe. The runtime broker checks grants, bindings, and active connections; MCP policy controls which structured tools are materialized; user approval addresses consequential effects. Explicit `server.tool` allowlists are narrower than discovery, and policy changes apply on a later run. Local-first keeps key state under local control, but model providers, remote MCP, search, and integrations can still receive data. These boundaries support review, not a formal security audit.

Learning outcomes

A grant scopes account access; MCP policy controls callable tools; user approval confirms consequential effects, and none replaces the others.
An explicit MCP allowlist is narrower and more reviewable than discovery when required tool names are known.
Local-first keeps key state under local control, but it does not eliminate network exposure or prove provider retention behavior.

Keywords

holaOSgrantsaccountsMCPapprovalbroker

The Security Boundary Runs Through Grants, Accounts, and Tools

In holaOS, giving an agent a capability is not the same as giving it unrestricted authority. This chapter follows an app request through grants, account bindings, brokered transport, MCP policy, and user approval, then separates local control from local-only execution. The practical goal is to judge an actual workspace: which account can an app reach, which tools can this run call, which actions still need confirmation, and what data may travel beyond the machine?

The question matters because an agent that can read a workspace, call an app, browse a page, or send a message sits on several trust boundaries at once. A polished interface can make those boundaries feel like one permission. In holaOS, they are deliberately split, although the splits do not remove the need for careful configuration or trust in app and provider code.

A grant is a route to an account, not the account itself

An app that needs Gmail, GitHub, Slack, or another external service declares an integration requirement. The runtime resolves that requirement against an app-level or workspace-level binding and supplies the app with a broker route and an app grant. The app's normal production path does not need to treat the provider's raw credential as ordinary environment data. It sends a structured request to the runtime broker, which uses the grant and the binding to determine whether the request belongs to the right workspace, app, and provider.

That extra hop changes the failure model. A provider token on its own answers “can this credential authenticate?” It does not necessarily answer “which app is using it, in which workspace, under which binding, and is the connection still active?” The broker can make those checks before it attempts the provider operation. In the current implementation, it validates a signed grant when available, resolves the app or workspace binding for the requested provider, rejects a missing binding, checks that the connection is active, and then selects an appropriate transport.

For a managed Composio connection, the broker proxies the request through the linked external account. For a compatible non-Composio connection, the broker can resolve and refresh a bearer credential before making the provider request. The App Builder SDK's runtime-broker transport sends the grant, provider id, HTTP method, endpoint, and request body to the broker rather than embedding a provider-specific auth flow in every app. That makes the runtime the place where account selection and transport policy can be observed and changed.

sequenceDiagram participant A as App participant B as Runtime broker participant G as Grant and binding checks participant R as Runtime action policy participant U as User participant P as Provider or Composio A->>B: Submit provider request with app grant B->>G: Validate grant, binding, and active connection alt Grant, binding, or connection fails G-->>B: Typed broker failure B-->>A: not connected or unavailable else Access is authorized B->>R: Pass authorized request to action policy opt Approval policy applies R-->>U: Show proposed consequential action U-->>R: Approve or cancel end alt User cancels R-->>A: Action stopped before provider call else Request proceeds R->>B: Permit provider request B->>P: Proxy or bearer request P-->>B: Provider status and response B-->>A: Typed success or provider failure end end

The broker is a control point, not a universal safety certificate.

Published by DeepMox

FAQ

What does a holaOS grant authorize?

A holaOS grant authorizes an app's route to a provider account within the relevant workspace, app, binding, and scope; it does not approve every request.

Why are approval and authentication separate in holaOS?

In holaOS, grants and bindings establish which account and scope may be used, while approval asks whether the user wants a consequential action to happen now.

Which network paths can a holaOS workspace still use?

Depending on configuration, a holaOS workspace can use model providers, embeddings or reranking, web search, remote MCP servers, and external integrations.

Previous11 minholaOS Apps: Lifecycle and Capability Ownership

Next11 minholaOS Memory: Resume, Recall, Verify

holaOS Security: Grants, Accounts, and Tools

The Security Boundary Runs Through Grants, Accounts, and Tools

A grant is a route to an account, not the account itself

FAQ