---
title: Setup App
description: The platform's built-in administration UI — what it is, what it shows, and how it is wired
---

# Setup App

The **Setup App** (`/_studio/apps/setup`) is the built-in administration
console for every ObjectStack project. It lists every `sys_*` platform
object, plus two pre-baked dashboards, behind a fixed left-hand
navigation tree.

It used to be assembled at runtime by a dedicated `SetupPlugin` (which
walked every loaded plugin asking "do you contribute Setup entries?").
That plugin is **gone** as of the static-Setup-App refactor — the entire
app is now a fixed metadata artifact exported from
`@objectstack/platform-objects` and registered exactly like any other
ObjectStack app.

## Where it lives

| File | Role |
|:---|:---|
| `packages/platform-objects/src/apps/setup.app.ts` | The `App` definition — navigation tree, branding, required permissions |
| `packages/platform-objects/src/apps/dashboards/system_overview.dashboard.ts` | "Overview → System Overview" dashboard |
| `packages/platform-objects/src/apps/dashboards/security_overview.dashboard.ts` | "Overview → Security Overview" dashboard |
| `packages/platform-objects/src/apps/views/*.view.ts` | List views referenced by the navigation entries |
| `@objectstack/plugin-auth` | Performs the runtime registration via `manifest.register({...})` (auth is always loaded alongside security + audit) |

> Why does `plugin-auth` register Setup? Because the Setup App's
> `requiredPermissions: ['setup.access']` permission is contributed by
> `plugin-auth`. Co-locating registration with the permission source
> avoids load-order surprises.

## Navigation

Menu shape: a flat `navigation[]` array with `type: 'group'` category
nodes and `type: 'object' | 'dashboard'` leaves — the same convention used
by the CRM example app.

| Group | Entries |
|:---|:---|
| **Overview** | System Overview · Security Overview |
| **Administration** | Users · Organizations · Teams · API Keys · Roles · Permission Sets · **OAuth Apps** · **Signing Keys** |
| **Platform** | Objects · Views · Flows · AI Agents · AI Tools · Apps · Packages · Installations · All Metadata |
| **System** | **Sessions** · Audit Logs · **Activity** · **Comments** |

Bold entries are recently added:

- **Sessions** (`sys_session`) — better-auth session records (used to be
  in a separate ad-hoc table; now part of the platform schema).
- **OAuth Apps** (`sys_oauth_application`) — third-party OAuth client
  registrations (e.g. for the Account portal).
- **Signing Keys** (`sys_jwks`) — JWKS keys used for OIDC / JWT signing.
- **Activity** (`sys_activity`) — high-level activity feed (audit log
  optimised for human reading; the technical audit trail still lives in
  `sys_audit_log`).
- **Comments** (`sys_comment`) — user-authored comments on records, used
  by the Studio inspector and any object that opts into a comment thread.

## Why it is static

The previous `SetupPlugin`-based design existed because the referenced
objects used to live in three different runtime plugins (auth / security
/ audit), each of which registered its own Setup entries dynamically.
Now that all `sys_*` objects are centralised in
`@objectstack/platform-objects`, the navigation tree is also fixed at
build time. Benefits:

- One file to read to understand what Setup contains.
- No load-order dependency between Setup and the plugins it references.
- The artifact can be type-checked against `App` from
  `@objectstack/spec/ui` without any runtime plugin context.

## Customising it

The static export is intentionally read-only. To add a new entry:

1. Add the object/dashboard/view to `@objectstack/platform-objects`
   (or to a project-local plugin if it is project-specific).
2. Add a `navigation[]` leaf under the appropriate group in
   `packages/platform-objects/src/apps/setup.app.ts`.
3. If the entry needs its own permission, declare it in
   `@objectstack/plugin-auth` so the `requiredPermissions` check picks it
   up.

For project-local Setup-style entries, define a separate App in your
project — Setup is reserved for platform-level administration.

## Related

- [App Metadata](../guides/metadata/app) — `App` schema reference
- [Authentication](../guides/authentication) — where `setup.access` is granted
- [Cloud Deployment](../guides/cloud-deployment) — how Setup behaves in cloud mode
