# Building BuilderIO/agent-native from Source: Root File and Monorepo Configuration > Build BuilderIO/agent-native from source by configuring package.json, pnpm-workspace.yaml, and prebuild scripts to compile the core framework. Master your monorepo setup. - Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native) - Tags: internals - Published: 2026-07-01 --- **To successfully build BuilderIO/agent-native from source, you must configure the root [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) postinstall pipeline, [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) workspace definitions, and execute the [`scripts/prebuild-workspace-packages.ts`](https://github.com/BuilderIO/agent-native/blob/main/scripts/prebuild-workspace-packages.ts) orchestrator that compiles core framework packages before any template application can run.** BuilderIO/agent-native is an open-source framework that tightly couples AI agents with real web applications through a unified action surface. When building from source, understanding the root file structure and workspace configuration is essential because the repository uses a pnpm-powered monorepo where core libraries must be prebuilt before template apps can consume them. The root-level configuration files govern how the framework compiles, links, and executes across the `packages/` and `templates/` directories. ## Root File Architecture and Workspace Configuration The repository root contains several critical files that define the build environment and development workflow. These files establish the monorepo boundaries and ensure the core framework (`@agent-native/core`) is available to template applications. ### package.json and Build Orchestration The root [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) defines the workspace-wide scripts and triggers the postinstall build process. According to the source analysis, the `postinstall` script automatically executes [`scripts/prebuild-workspace-packages.ts`](https://github.com/BuilderIO/agent-native/blob/main/scripts/prebuild-workspace-packages.ts) immediately after dependency installation【/cache/repos/github.com/BuilderIO/agent-native/main/package.json#L22-L24】. Key root scripts include: - `pnpm install` – Triggers the postinstall hook to build all workspace packages - `pnpm run dev:all` – Builds core then starts every template on sequential ports - `pnpm run prep` – Runs formatting, type checking, tests, and CI guards locally The postinstall script is critical because it compiles TypeScript sources in `packages/core/` and other workspace members, making them importable by the template applications located in `templates/mail/`, `templates/calendar/`, and others. ### pnpm-workspace.yaml and Package Linking The [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) file defines which directories are included in the monorepo workspace. This configuration enables the pnpm linker to resolve internal dependencies like `@agent-native/core` from the local `packages/core/` directory rather than from the npm registry. The workspace typically includes: - `packages/*` – Core framework libraries, UI components, and dispatch services - `templates/*` – Production-ready SaaS template applications (Mail, Calendar, Clips) Without this workspace definition, the template apps would fail to resolve the local framework dependencies during the build process. ### DEVELOPMENT.md and Local Setup Guidelines The [`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md) file in the repository root provides the authoritative guide for prerequisites and environment setup. It documents the requirement for pnpm as the package manager and specifies the commands for running individual packages versus the entire monorepo【/cache/repos/github.com/BuilderIO/agent-native/main/DEVELOPMENT.md#L20-L30】. ## Core Build Pipeline and Source Files Building from source requires understanding how the root scripts compile the framework before applications can start. ### The Prebuild Workspace Script The [`scripts/prebuild-workspace-packages.ts`](https://github.com/BuilderIO/agent-native/blob/main/scripts/prebuild-workspace-packages.ts) file serves as the primary build orchestrator. This TypeScript script runs during the postinstall phase and compiles all packages in the correct dependency order. It ensures that [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts) and other framework entry points are transpiled and ready for import. The script handles the **action definition surface** (`defineAction`) that powers the entire framework, located in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts). This file implements the unified API surface that exposes actions as React hooks, LLM tools, and CLI commands. ```bash # Clone and initial build git clone https://github.com/BuilderIO/agent-native.git cd agent-native pnpm install # Automatically triggers prebuild-workspace-packages.ts ``` ### Template Application Structure After the root build completes, template applications can resolve their dependencies. Each template (e.g., `templates/mail/`) contains its own [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) that references the workspace versions of `@agent-native/core` and other packages. The templates share a common structure: - [`src/schema.ts`](https://github.com/BuilderIO/agent-native/blob/main/src/schema.ts) – Drizzle ORM schema definitions for SQL-backed state - `actions/` – Directory containing action definitions using `defineAction` - [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) – Dependencies linked to the monorepo workspace ## Development Workflow Essentials Once root files are configured and the initial build completes, you can run specific parts of the monorepo. ### Running the Entire Monorepo To verify your build from source, use the root-level command: ```bash pnpm run dev:all ``` This command builds the core framework and then launches every template application on sequential ports, allowing you to test the full integration of the agent runtime, UI components, and action definitions. ### Targeting Individual Packages For development efficiency, target specific workspace members: ```bash # Run only the mail template pnpm --filter mail dev # Watch-build the core framework only pnpm --filter @agent-native/core dev ``` ### CLI Action Execution The root configuration enables direct action invocation via CLI: ```bash pnpm action send-email ``` This command executes the `send-email` action defined in the templates, using the same code path that the UI and agent runtime utilize. ## CI Guards and Verification Root-level guard scripts enforce code quality and prevent deployment issues. These scripts run during `pnpm run prep` and in CI ([`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml)): - `scripts/guard-no-drizzle-push.mjs` – Prevents accidental production database pushes - `scripts/guard-no-env-credentials.mjs` – Blocks hard-coded secrets - `scripts/guard-no-unscoped-queries.mjs` – Ensures database queries are properly scoped Running these guards locally ensures your source build meets repository standards before pushing changes. ## Summary - **Root [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json)** triggers [`scripts/prebuild-workspace-packages.ts`](https://github.com/BuilderIO/agent-native/blob/main/scripts/prebuild-workspace-packages.ts) during postinstall to compile the framework - **[`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)** defines the monorepo boundaries for `packages/` and `templates/` directories - **[`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md)** provides the canonical reference for building and running from source - **Template apps** depend on the prebuilt core packages; run `pnpm install` first to establish the workspace links - **Guard scripts** in `scripts/` validate the build before CI submission ## Frequently Asked Questions ### What is the first file I should check when building from source? You should examine [`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md) immediately after cloning. This root file contains the prerequisite list, pnpm version requirements, and the command reference for building the monorepo workspace correctly. ### Why does `pnpm install` take longer than a typical npm install? The installation process executes [`scripts/prebuild-workspace-packages.ts`](https://github.com/BuilderIO/agent-native/blob/main/scripts/prebuild-workspace-packages.ts) as a postinstall hook, which compiles TypeScript sources in `packages/core/` and other workspace members. This step is necessary to make the framework packages available to the template applications before you can run `pnpm run dev:all`. ### Can I build just the core framework without the templates? Yes. Use the filter command `pnpm --filter @agent-native/core build` to target only the core package. This is useful when modifying [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts) or the agent runtime in [`packages/core/src/agent/production-agent.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/agent/production-agent.ts) without needing to start the full template applications. ### What happens if I skip the root-level guards? Skipping the guard scripts (located in `scripts/guard-*.mjs`) may result in CI failures or accidental deployment issues. The `guard-no-drizzle-push.mjs` script specifically prevents database schema changes from being pushed to production environments during development, while `guard-no-env-credentials.mjs` ensures no secrets are committed to the repository.