Technical Guide: Implementing AI App Builder Open

Overview and Core Functionality

The AI App Builder Open is an open-source, self-hosted interface designed to facilitate the creation of full-stack Next.js applications. By leveraging the Totalum API, the tool acts as a front-end layer that translates user prompts into functional software. It handles the complexities of infrastructure, including database provisioning, file storage, SSL, CDN, and deployment, allowing developers to focus on the application logic rather than the underlying server management.

The system is built to be modular and white-label, making it suitable for integration into existing SaaS platforms. It provides a comprehensive workspace that includes a live preview, a Monaco-based code editor, a visual editor for UI adjustments, and database management tools. Because it is designed as a thin client, it does not require complex glue code; instead, it relies on a single API key to interface with the Totalum backend. This architecture ensures that the builder remains lightweight while providing powerful capabilities for generating, previewing, and deploying complex web applications.

Prerequisites and Initial Setup

To deploy the builder, you must have Node.js 20+ and npm installed on your local machine or server. The setup process is straightforward, requiring the cloning of the repository and the installation of dependencies. The application relies on a single environment variable, TOTALUM_VCAAS_API_KEY, which must be obtained by creating an account at https://www.totalum.app/api. This key is essential for all operations, including hosting and AI generation.

The following commands are used to initialize the project:

git clone https://github.com/totalumlabs/ai-app-builder-open.git
cd ai-app-builder-open
npm install

Once installed, you must create a .env or .env.local file in the root directory to store your API key. It is critical to note that this key is read exclusively on the server side and is never exposed to the browser, ensuring a secure communication channel between your instance and the Totalum infrastructure. The application is designed to be highly portable, avoiding platform lock-in while maintaining the benefits of the managed Totalum backend.

Documented Workflow and Integration

The workflow begins when a user submits a prompt, such as a request for a CRM or a SaaS MVP. The AI agent processes this input to generate a complete Next.js project. Users can then interact with the generated code through the built-in editors. The visual editor allows for real-time changes to UI elements, which are automatically written back to the source files. For more advanced users, the platform supports GitHub synchronization, allowing for bidirectional code management. Every project has a live URL, and users can publish to production in one click.

For those looking to integrate this into a larger product, the builder is multi-tenant by design. You can create isolated projects for individual users or customers. Integration can be achieved by running the builder on a subdomain or by porting the underlying contract into your existing stack. The documentation provides specific guidance on using the builder as a boilerplate, including how to implement authentication via providers like Supabase and payment processing via Stripe. This allows developers to build a custom SaaS experience while offloading the heavy lifting of AI-driven code generation to the Totalum API.

Security, Limitations, and Deployment

A significant limitation of the default repository is that it ships without an authentication layer. This is a deliberate design choice to allow developers to implement the specific auth system that fits their existing architecture. Before deploying to a public environment, you must protect the routes defined in src/proxy.ts and implement guards in src/app/api/vcaas/_shared.ts. Failure to do so will allow any user with access to the URL to consume your API credits. The system is designed to be highly portable, avoiding platform lock-in while maintaining the benefits of the managed Totalum backend.

Deployment is flexible, as the project is a standard Next.js application. It can be hosted on Vercel using the provided one-click deployment button or on any Node.js-compatible host, such as Docker, Railway, or Render. When deploying, ensure that the TOTALUM_VCAAS_API_KEY is correctly configured in your host's environment variables. By following these steps, you can successfully integrate the AI App Builder into your own product, providing your users with a seamless, white-labeled experience for building full-stack applications.