`; core owns the Account, Connections, Agent, and
Organization pages, and the app supplies only its own content.
```tsx
import {
SettingsTabsPage,
useAgentSettingsTabs,
} from "@agent-native/toolkit/app/settings";
export default function SettingsRoute() {
const agentSettingsTabs = useAgentSettingsTabs();
return (
}
appAreas={[
{ id: "meetings", label: "Meetings", content: },
]}
notifications={}
mcpAbout="Record, search, and share clips from any MCP host."
whatsNewMarkdown={changelog}
/>
);
}
```
Settings brings its own back link to the app, navigation, and page header, so
the app layout hides its sidebar and header on Settings routes
(`isSettingsPathname(pathname)`).
| Prop | Where it shows |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `generalGroups` | The app's own `SettingsGroup`s on App › General, between core's Agent › Default model and This browser › Demo mode. |
| `appAreas` | Tabs on App › General, routed `/settings/app/`: `{ id, label, content, visible?, icon?, keywords?, searchEntries? }`. |
| `notifications`, `notificationsSearchEntries` | App › Notifications. The page shows only when `notifications` is passed. |
| `mcpAbout` | The translated about line on App › MCP server, naming what an MCP host can do in this app. |
| `labs` | Lab definitions on the Labs page. |
| `whatsNewMarkdown` or `whatsNew` | What's new, with an unread dot until visited. |
| `appName`, `appIcon`, `appId` | The app group's label and icon. They default to the template's own. |
| `extraTabs` | Other app tabs. Each becomes its own page in the app's group; `settingsPlacement: "app-area"` makes it a tab on App › General instead. |
Set `visible: false` on an app area while the lab behind it is off. `useLab(ref)`
and `useLabState(ref)` take a `LabReference`, either a key or
`{ key, defaultEnabled? }`; pass the lab definition rather than a bare key so
the lab reads as its `defaultEnabled` while labs load. Don't add a default-model, language, or demo
mode row to the app's groups: core already renders them.
### Registering a page {#registering-a-page}
An app page usually starts as an `extraTabs` item, which becomes its own page
in the app's group. For more control, register a `SettingsPageDefinition`
(`id`, `group`, `order`, `label`, `icon`, `component`, and optional `visible`,
`subpages`, and `searchEntries`) with `registerSettingsPages` at module scope. A definition
with the same id as an existing page replaces it, which is how an app swaps a
core page for its own variant. Dispatch keeps its app-role column on Members
this way:
```tsx
import { OrgMembersPage } from "@agent-native/toolkit/app/org";
import {
CORE_SETTINGS_PAGES,
registerSettingsPages,
} from "@agent-native/toolkit/app/settings";
const coreMembersPage = CORE_SETTINGS_PAGES.find(
(page) => page.id === "members",
)!;
registerSettingsPages([
{
...coreMembersPage,
component: () => ,
},
]);
```
A page component receives `{ pageId, sub, context, bridge }`, where `context`
carries the viewer's role, labs, and flags. Inside a page,
`useSettingsPageHeader({ title?, action?, badge? })` sets a sub-page breadcrumb,
the header's primary action, or a chip beside the title.
An app adds a section to one channel's page with
`registerChannelSettingsExtensions([{ id, platform, component }])` at module
scope next to its settings route. Clips and Mail use it for their Slack groups.
## Links {#links}
Never hand-write `/settings/...` strings. Build links with the route helper:
```ts
import { buildSettingsRoute } from "@agent-native/core/client/navigation";
buildSettingsRoute("integrations", "builder"); // /settings/integrations/builder
buildSettingsRoute("app", "recordings"); // /settings/app/recordings
buildSettingsRoute("model", null, { anchor: "limits" }); // /settings/model#limits
```
Older links keep working. Earlier tab ids (`agent`, `keys`, `team`), nested ids
(`agent:resources:memory`), section hashes (`#llm`, `#secrets:OPENAI_API_KEY`),
and `agent-panel:open-settings` sections all resolve through one redirect table
in `packages/core/src/navigation/settings-redirects.ts`. To move an old link,
change its row there and add a case to `settings-redirects.spec.ts`.
`openSettingsPage(page?)` from `@agent-native/core/client/navigation` opens
Settings from anywhere, including outside the router. `AppProviders` already
binds ⌘, through `useSettingsShortcut()`, so an app never binds it again.
## Search {#search}
Search indexes page names plus the `searchEntries` each page declares, without
rendering the pages. A result shows the row label and its location
("Agent › Model"); Enter opens it and flashes the row.
- On a page definition, a search entry's `anchor` is the row's `SettingsRow` id.
- On an app area or `notificationsSearchEntries`, the entry's `hash` is the
row's `SettingsRow` id.
- Add `keywords` for synonyms and provider names the label doesn't contain,
for example "S3", "R2", and "bucket" for file storage.
Give each searchable `SettingsRow` or `SettingsGroup` a stable `id`. Those ids
are link anchors too, so don't rename one.
## Agent parity {#agent-parity}
Everything on these pages can be read and changed by the agent through actions,
and the agent knows which page the user has open:
- The Settings shell writes application state `settings-view` =
`{ page, sub, label }` for the browser tab, and `` shows it as
`settingsPage: integrations/builder (Connections › Integrations › Builder.io)`.
- The built-in `open-settings-page` tool opens any page by id, with an optional
`sub` and `anchor`. Earlier tab and section ids work there too.
| Page | Actions |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Profile | `get-user-profile`, `update-user-profile` |
| Integrations › Builder.io | `manage-builder-connection` |
| API keys | `list-api-keys`, `preview-secret-removal`, `delete-api-key` |
| Model | `list-model-providers`, `check-provider-key`, `get-provider-models`, `manage-provider-models`, `manage-provider-key-policy`, `manage-agent-engine` |
| Usage | `get-usage-metrics`, `manage-usage-alert` |
| Authentication | `list-sign-in-methods` |
| Apps | `list-workspace-app-access`, `set-workspace-app-access` |
| Infrastructure | `get-infrastructure-status`, `get-file-storage`, `manage-file-storage`, `manage-service-providers` |
| Audit log | `list-audit-events`, `get-audit-event`, `export-audit-events` |
| App › Automations | `manage-automations` |
| App › Channels | `list-messaging-channels`, `manage-messaging-channel` |
An app's own rows follow the same rule: every control on `generalGroups`,
`appAreas`, or `notifications` saves through an app action the agent can call.
## Roles {#roles}
| Capability | Member | Admin | Owner |
| --------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------- | ------------------ |
| Account pages, connecting integrations for themselves | Yes | Yes | Yes |
| Personal providers and a personal Builder.io account | Yes, unless restricted | Own keys; use Builder.io for the organization | Same as admin |
| Organization providers, default model, max iterations, Restrict personal API keys | Read-only | Yes | Yes |
| Organization instructions, memory, skills, and files | Read-only | Yes | Yes |
| Invite members | No | Members | Members and admins |
| Change member roles | No | No | Yes |
| Authentication, Apps, Infrastructure, Audit log | Hidden | Yes | Yes |
| Shared A2A secret, delete the organization | No | No | Yes |
Owners and admins run on the organization's provider keys and Builder.io connection first, with their own as the fallback; members run on their own first. When saving a key, owners and admins save it for the organization by default and can pick **Personal**; members save personally.
## UX standard {#ux-standard}
- Keep durable settings in Settings. The agent sidebar links into a page
instead of rendering settings inline.
- A provider key is added, changed, and removed in one dialog, whichever page
opened it.
- Read-only rows show the value with a lock and a tooltip naming who can change
it (`ReadOnlySettingValue`). Removing a key, disconnecting Builder.io, or
restricting personal keys opens a confirm dialog that lists what stops
working.
- Rows are a label, an optional description, and one control. No page
subtitles, eyebrows, or count strips.
- Register a search entry for every meaningful row.
## Sign in with ChatGPT for open-source apps {#chatgpt-subscription-lab}
Agent-Native uses OpenAI's official Sign in with ChatGPT token-sharing flow for
eligible open-source use. It authorizes the local app to make eligible requests
to OpenAI's public Responses API with the signed-in user's ChatGPT plan. It does
not grant access to the user's ChatGPT conversations or history.
ChatGPT plan access is off by default. Enable the **ChatGPT plan access** lab
in **Settings → Labs** before connecting ChatGPT.
Open-source apps running locally need neither OpenAI partner approval nor a
preconfigured client ID. At first sign-in, OpenAI issues a client ID, and the
app saves it for later sign-ins with that ChatGPT account.
ChatGPT plan access requires a personal account. For local development, set
`access.autoCreateDefaultOrg: false` before the first sign-in so the app does
not create a default organization for that account. If an account already
belongs to an organization, use a personal account for ChatGPT plan access.
The OAuth callback must use `http://127.0.0.1` on the user's machine.
`localhost` is not an accepted substitute. The self-serve flow does not support
hosted `*.agent-native.com` sites or paid deployments. Supporting ChatGPT plan
access on a hosted site requires both OpenAI partner approval for the app
operator and a hosted implementation. The operator can request approval through
OpenAI's [interest form](https://openai.com/form/sign-in-with-chatgpt-interest).
### Connect ChatGPT
Open **Settings → Agent → Model** and connect ChatGPT in the personal providers
list. Sign in with the ChatGPT account whose plan you want to use, then approve
the requested access. After connecting, choose an available model in the chat's
model picker. You can disconnect ChatGPT from the same settings row. If
OpenAI cannot confirm remote revocation, local tokens are still cleared; use the
warning link to manage this app's access in ChatGPT Settings → Usage.
Use only the public Responses API for inference. ChatGPT's private backend
endpoints and ChatGPT conversation data are outside this authorization. OpenAI
marks the token-sharing flow as a preview, so model availability, limits, and
supported API features can change. Review OpenAI's [Sign in with ChatGPT
overview](https://developers.openai.com/siwc/token-sharing-open-source),
[registration and sign-in](https://developers.openai.com/siwc/token-sharing-open-source/sign-in),
[accounts and sessions](https://developers.openai.com/siwc/token-sharing-open-source/profiles-and-sessions),
[models and inference](https://developers.openai.com/siwc/token-sharing-open-source/models-and-inference),
[preview limitations](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations),
[error recovery](https://developers.openai.com/siwc/token-sharing-open-source/errors-and-recovery),
and [UI/UX guidelines](https://developers.openai.com/siwc/ui-ux-guidelines).
## What's next
- [**Internationalization**](/docs/internationalization) — localize the app's
settings copy.
- [**Onboarding**](/docs/onboarding) — register the setup steps that settings
deep links jump users to.
- [**Workspace Connections**](/docs/workspace-connections) — the shared
provider-connection model behind provider readiness.