--- title: "How to build CrewOS" section: "How-To Do This" canonical_url: "https://support.buildwithhq.com/how-to-do-this/crewos.html" reviewed_at: "2026-09-14" authority: Official --- # How to build CrewOS Build a governed team of specialized AI operators with shared records, approval boundaries, and replayable execution evidence. ## In brief - **Pattern:** AI agent workforce - **First release:** One agent, one approved action - **Build surface:** Developer Console **CrewOS** follows the **AI agent workforce** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/crewos.html) into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging. Note CrewOS is now implemented and live-proven as the first product-specific Build This production solution. Its governed team roster, three managed record families, six published pages, favorites, secured file attachments, relationships, activity, approval boundaries, and deactivation lifecycle were exercised against a route-resolved disposable tenant and render-checked on desktop and mobile. It is not yet a Template Library listing; exact-version template packaging is intentionally later work. [Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html) ## Define the outcome before the screens Give each agent a narrow job, permitted context, declared tools, and a measurable handoff. The product is successful when a person can see what the agent learned, approve or refuse its proposed work, and reconstruct what happened afterward. Note Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries. ## 1. Create the smallest useful data model In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records. | Record type | What it holds | | --- | --- | | **Agent profile** | Role, instructions, enabled tools, authority ceiling, owner, and active version. | | **Work request** | Goal, requester, priority, source record, current state, and due time. | | **Suggestion batch** | The plan produced from one activity version and its supporting context. | | **Action suggestion** | A proposed narrow operation, inputs, risk, evidence, and approval state. | | **Action execution** | The authorized operation, executor, result, correlation ID, and failure evidence. | | **Rating** | Human outcome, quality score, correction, and reusable feedback. | **Relationship rule:** Relate every request to its source business records; keep suggestions, approvals, executions, and ratings as an unbroken chain. ## 2. Build the working screens Start with task-oriented pages instead of a page for every table. The first navigation should contain: - Mission control with agent availability and bounded queue health. - Work-request detail with source context and plan. - Approval queue showing evidence, risk, and exact proposed changes. - Execution timeline and failure evidence. - Ratings and outcome review by agent/version. Use [Puck](../builder-guide/page-editor.html) for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html) so future template upgrades can merge safely. ## 3. Set access before adding automation - Separate who may request work, inspect context, approve an action, and operate agents. - Apply the source record's normal DataRole, field, and location rules to agent context. - Set explicit authority ceilings for customer-facing, financial, destructive, and external actions. User Type menus establish eligible page routes for each audience. They do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request. ## 4. Add the core workflows - Request → read-only planning → suggestion batch. - Suggestion → policy check → approval or refusal. - Approved suggestion → deterministic queued execution → recorded result. - Material source activity change → mark the old plan stale and require preparation again. - Completed work → human rating → versioned improvement input. Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs. ## 5. Connect channels and outside systems - Expose only declared, action-specific APIs as agent tools. - Route external calls through managed connections or appliance endpoints. - Send approval and failure attention to Universal Inbox without moving the source record into the inbox. Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page. ## 6. Add AI as a governed layer Use GoClaw as the planner/worker and the canonical suggestion/execution contracts as the boundary between reasoning and mutations. Agent memory may assist retrieval, but it does not replace application records or authorization. - Start with read-only retrieval against one record family. - Require structured suggestions with evidence and expected current state. - Preserve the Inbox `ActivityVersion` fence through preparation, approval, and execution. - Evaluate exact harness/agent versions and retain ratings by version. AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution. ## 7. Ship one complete vertical slice **Recommended first release:** A research agent reads one permitted account, prepares a follow-up task, and an authorized person approves task creation. A changed source activity invalidates the pending suggestion. 1. Create the minimum record types and seed representative, non-production data. 2. Build the primary list/queue and one complete detail page. 3. Implement one state-changing workflow and its denial/error states. 4. Add the narrowest useful integration or inbound channel. 5. Add one permission-aware AI read or suggestion only if it improves that workflow. 6. Test as an owner, a normal operator, a restricted user, and an unauthorized user. ## 8. Validate, package, and operate - Prove an unauthorized agent cannot retrieve the record. - Prove refused and stale suggestions cannot execute. - Retry execution without producing duplicate work. - Trace request, approval, tool call, and result by correlation ID. Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html) when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html) checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy. **Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence. Tip A useful first agent removes one recurring preparation step. Add more roles only after its permissions, approvals, and outcome measurements are trustworthy. --- Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/crewos.html).