# Building Rome Apps URL: /docs/building-apps Markdown: /docs/building-apps.md Description: A short guide to choosing, structuring, and shipping Rome Apps. Rome Apps extend a private Rome environment with durable product surfaces: actions, app-private agents, skills, hooks, routines, databases, HTTP APIs, and web UIs. This page is the high-level guide. Use it to choose the right shape for an app, then follow the linked detail pages when you are implementing. ## Design Guidelines [#design-guidelines] Build an app when the user needs a place that owns state, not just a one-shot workflow. A good Rome App has a clear product surface, saves user-facing records before it starts long-running work, and still shows useful state after the user refreshes, leaves, or comes back tomorrow. Use these rules as the default: * Give important app views stable URLs, including detail pages that can be shared and reopened. * Keep the first screen focused on saved state and the main actions the user can take next. * Treat UI-triggered long work as a saved job with a visible status, not as a browser request that must stay open. * Design mobile-first. Rome apps run inside the dashboard on phones as well as desktop. * Check existing open-source SVG icon sets before drawing or adapting a custom app icon. * Write App Store listing copy for users, not for implementers. Keep technical details in source docs and commits. * Use Title Case display names rather than the kebab-case `appId`. See [Design Guidelines](/docs/building-apps/design-guidelines) for the full deep-link, state, mobile, icon, and README rules. ## General Architecture [#general-architecture] Every app starts with an `app.yaml` manifest. The manifest declares the app identity and lists only the artifacts the app actually ships. The daemon loads declared artifacts from the built app root, so the source tree, manifest, and build output must stay aligned. Read the architecture in this order: * [Quickstart](/docs/building-apps/quickstart): decide whether the request should be an app, scaffold it, install it, and iterate from a git-tracked source tree. * [App Structure & app.yaml](/docs/building-apps/app-structure): understand the root files, `src/` layout, manifest fields, validation rules, and how `appId` relates to URLs, paths, and database table prefixes. * [Build, Install & Iterate](/docs/building-apps/build-install-lifecycle): separate local CLI feedback from daemon installs, and use `system:app_management` for the running app lifecycle. * [Capabilities](/docs/building-apps/capabilities): choose which artifacts your app needs instead of keeping every scaffolded feature. Apps communicate with Rome through public SDKs and platform registries, not by importing Rome Core source. Backend code uses `@rome-os/app-runtime`; frontend code uses `@rome-os/app-web-sdk`. Other app functionality should be reached through registered actions, app APIs, events, routines, or the app's own database layer. ## The SDK packages [#the-sdk-packages] The docs are organized by capability, not by package. If you're arriving from npm, this is where each package entry point is documented: | Import | What it covers | Documented in | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `@rome-os/app-runtime` | Backend SDK: actions, agents, hooks, database, HTTP API, WebSockets, routines & events, favors, telemetry | [Actions](/docs/building-apps/capabilities/actions), [Agents](/docs/building-apps/capabilities/agents), [Hooks](/docs/building-apps/capabilities/hooks), [Database](/docs/building-apps/capabilities/database), [HTTP API](/docs/building-apps/capabilities/http-api), [WebSockets](/docs/building-apps/capabilities/websockets), [Routines](/docs/building-apps/capabilities/routines), [Events](/docs/building-apps/capabilities/events), [Favor Request Actions](/docs/building-apps/capabilities/favor-request-actions), [Telemetry](/docs/building-apps/capabilities/telemetry) | | `@rome-os/app-runtime` caller gating (`requireVisitor`) | Enforcing who may call an app-api route | [Public Access & Caller Identity](/docs/building-apps/public-access) | | `@rome-os/app-runtime/browser` | Driving the agent browser over CDP from backend code | [Browser Automation](/docs/building-apps/capabilities/browser-automation) | | `@rome-os/app-web-sdk` | Frontend SDK: bootstrap, `fetchAppApi`, routing & deep links, host context, inline components, visitor sign-in UI | [Web UI](/docs/building-apps/capabilities/web-ui), [Public Access & Caller Identity](/docs/building-apps/public-access) | | `@rome-os/app-web-sdk/styles` | The style layer: Tailwind + host theme tokens | [Web UI → Styling](/docs/building-apps/capabilities/web-ui#styling-and-shadow-dom) | | `@rome-os/app-web-sdk/config` | Customizing the rslib build | [Build, Install & Iterate](/docs/building-apps/build-install-lifecycle#customizing-the-build-rslibconfigts) | | `rome` CLI (ships with `@rome-os/app-web-sdk`) | Local build/dev, version bumps, App Store publishing | [Build, Install & Iterate](/docs/building-apps/build-install-lifecycle), [App Store Submission](/docs/building-apps/app-store-submission) | ## API References [#api-references] Start with the capability page that matches what you are building: * [Actions](/docs/building-apps/capabilities/actions): define typed operations that agents, routines, webhooks, and other app code can run. * [Agents](/docs/building-apps/capabilities/agents): add app-private LLM agents when the app needs its own persistent collaborator. * [Skills](/docs/building-apps/capabilities/skills): ship plain-language instructions that agents load only when relevant. * [Hooks](/docs/building-apps/capabilities/hooks): react to runtime events such as incoming channel messages. * [Routines](/docs/building-apps/capabilities/routines): schedule actions to run later or repeatedly. * [Events](/docs/building-apps/capabilities/events): publish and consume domain events on the event bus. * [Database & Migrations](/docs/building-apps/capabilities/database): store app state with Drizzle tables and migrations. * [HTTP API](/docs/building-apps/capabilities/http-api): serve app-owned endpoints under the app API path. * [WebSockets](/docs/building-apps/capabilities/websockets): upgrade app API requests to live WebSocket connections. * [Web UI](/docs/building-apps/capabilities/web-ui): mount a React surface inside the dashboard and call app APIs from the browser. * [Favor Request Actions](/docs/building-apps/capabilities/favor-request-actions): require favor payment before dispatching selected hosted actions. * [Browser Automation](/docs/building-apps/capabilities/browser-automation): drive the agent browser over CDP from backend code. * [Telemetry](/docs/building-apps/capabilities/telemetry): add app spans to the instance's traces. When the app is ready to distribute, use the [App Store Submission](/docs/building-apps/app-store-submission) checklist.