# Quick Start
Source: https://docs.bult.ai/getstarted/quickstart



1. **Sign Up**: Visit [app.bult.ai/auth/signup](https://app.bult.ai/auth/signup) and use Google, GitHub, or email (magic link) to create an account. No credit card required.

   <img alt="Screenshot 2025-08-07 at 19.35.41.png" title="Screenshot 2025-08-07 at 19.35.41.png" />
2. **Create Workspace**: Name your workspace (e.g., “John’s Workspace”) and pick an icon color. Free tier includes 1 workspace.
3. **Create Project**: Start a project (up to 5 on free tier) in the Finland region. Name it (e.g., “Project1”) and click “Create.”
4. **Deploy an App**: On the Canvas page, click “+Create” to deploy a GitHub repo (e.g., Express.js) or Docker image (e.g., nginx:latest). Select XS compute size (0.1 CPU, 0.25 GB RAM, \$2.7/mo) and click “Create.”
5. **Explore**: Check your app’s URL (e.g., [https://project1.fin1.bult.app](https://project1.fin1.bult.app)) and monitor usage in the dashboard.

[Deploy Now](https://app.bult.ai/) | [Watch Demo](https://youtu.be/YdTwFjXZDGQ?si=9cXmakLUaLJy4Rtm)


# Welcome
Source: https://docs.bult.ai/getstarted/welcome

Deploy Fast, Build Without Limits!

Welcome to the official documentation for Bult, a DevOps platform that lets you deploy apps and databases in seconds without server management. Whether you're a software engineer, product manager, or startup, Bult’s Canvas UI, 1-click templates, and intuitive developer experience make DevOps effortless.

### About

We're on a mission to remove infrastructure headaches so developers can build faster, ship more, and create far more impactful systems.

Our goal is to make it effortless for engineers to deploy code without worrying about servers.

Infrastructure automation = massive leverage.

Bult is a Platform-as-a-Service, designed to eliminate DevOps complexity. Launched in June 2025, we serve thousands of active users, including software engineers, product teams, and startups, with a Starter plan (\$5/mo) with \$5 free credits to start and a Pro plan (\$20/mo, launching soon). Our Canvas UI and ready-to-use templates, simplify deployments for Node.js, MongoDB, FastAPI, and more.


# Backups
Source: https://docs.bult.ai/guides/backups



Select database service, and go to Backups tab.

### **Daily Backups**

You can **Enable** or **Disable** schedule to automatically backup your data every day. No additional costs applied.

<img alt="Screenshot 2025 12 30 At 23 17 29" />

You can specify a time for automatic backups.

> Be aware,**your backups are only retained for 7 days** .

### Create manual backup

Service must be running to create a backup.

You can then download, restore or delete the backup.

<img alt="Screenshot 2025 12 30 At 23 27 18" />


# Builds
Source: https://docs.bult.ai/guides/builds



#### Build Configuration

Configure builds in Canvas UI’s “**Git**” tab:

* **Nixpacks**: Set install (npm install), build (npm run build), and start (npm run start) commands.
* **Dockerfiles**: Specify path (e.g., ./Dockerfile), context (e.g., .), and build stage (e.g., production).

#### Dockerfiles

Example Dockerfile for Node.js:

```
FROM node:18
WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "run", "start"]
```

Set custom start command in Canvas UI (e.g., npm run start).

#### Nixpacks

Auto-detect build settings for Node.js, Python, etc.


# CLI & Skills
Source: https://docs.bult.ai/guides/cli



Build more capable AI agents with reusable skills and platform-aware workflows.

## Overview

CLI is a command-line interface designed for AI-native workflows. It enables AI agents and developers to interact with applications, infrastructure, and deployment environments through a consistent interface.

Combined with Skills, agents can execute specialized workflows, understand platform-specific operations, and apply reusable knowledge across projects.

CLI provides a standardized execution layer that allows agents to:

* Deploy applications
* Manage infrastructure
* Execute operational workflows
* Access platform capabilities
* Automate repetitive tasks

## Getting Started

### 1. Generate an API Token

Before using CLI, create an API token from your Bult account.

1. Sign in to the Bult dashboard.
2. Navigate to **API Tokens**.
3. Click **Create Token**.
4. Copy and securely store the generated token.

> Keep your API token secure. Anyone with access to the token can perform actions on your behalf.

### 2. Install CLI

* Download latest [binary](https://github.com/bultcloud/cli/tags) release from GitHub
* or build from source:

```bash theme={null}
git clone https://github.com/bultcloud/cli.git
cd cli
make build
./bin/bult --help
```

Refer to the repository README for the latest installation instructions.

### 3. Authenticate

Authenticate directly using the CLI:

```bash theme={null}
bult login
```

## Skills

Skills are reusable knowledge packages that teach AI agents how to perform specific tasks.

Instead of repeating instructions in every conversation, teams can package expertise into Skills and make it available to all agents.

Examples include:

* Application deployment
* Environment management
* Troubleshooting workflows
* Security procedures
* Platform best practices

Skills enable agents to operate consistently and follow established engineering standards.

## Use Cases

### AI-Powered Operations

Allow AI agents to deploy services, inspect environments, and perform operational tasks through a controlled interface.

### Team Knowledge Sharing

Convert internal runbooks and platform expertise into reusable Skills that every agent can use.

### Platform Automation

Automate repetitive workflows while maintaining consistency and best practices.

CLI is available on GitHub: [https://github.com/bultcloud/cli](https://github.com/bultcloud/cli)


# Compute Sizes
Source: https://docs.bult.ai/guides/compute-sizes



Bult offers flexible compute sizes to match your app’s needs, billed per minute.

Free tier includes XS, S, and M.

Pro plan (September 2026) unlocks L to 3XL.

Configure in Canvas UI’s “**General**” tab in "**Edit Service**":

<img alt="Screenshot 2025-08-07 at 19.46.36.png" />

| Size | vCPU | RAM    | Price (Monthly) | Tier      | Use Case              |
| :--- | :--- | :----- | :-------------- | :-------- | :-------------------- |
| XS   | 0.1  | 256 MB | \$2.7           | Basic/Pro | Prototypes            |
| S    | 0.25 | 512 MB | \$5.4           | Basic/Pro | Small Apps            |
| M    | 0.5  | 1 GB   | \$12            | Basic/Pro | Web Apps              |
| L    | 1    | 2 GB   | \$24            | Pro       | APIs                  |
| XL   | 2    | 4 GB   | \$48            | Pro       | Databases             |
| 2XL  | 4    | 8 GB   | \$96            | Pro       | High-traffic          |
| 3XL  | 8    | 16 GB  | \$192           | Pro       | Enterprise-scale apps |

View Compute Sizes minutely, hourly, and monthly: [https://bult.ai/#pricing](https://bult.ai/#pricing).

**Details**:

* **Instances**: Free tier supports 1-2 instances per service; Pro allows up to 10.
* **Scaling**: Auto-scaling available with Pro plan. Manual scaling in Canvas UI.
* **Usage**: Monitor CPU/RAM in app.bult.ai/usage. Example: XS at 21.12 hours costs \$0.03 (CPU) + \$0.04 (RAM).
* **Limits**: Free tier caps at 0.5 vCPU, 1GB RAM total. Pro supports up to 8 vCPU, 16GB RAM.
* **Optimization**: Start with XS for prototypes. Upgrade to M/L for production to avoid “Out of capacity” errors.

**Example**: Deploy an Express.js app with XS compute:

1. Select “**GitHub Repository**” in Canvas UI.
2. Set compute to XS (0.1 vCPU, 0.25 GB RAM).
3. Deploy and monitor costs in [app.bult.ai/usage](https://app.bult.ai/usage).


# Database
Source: https://docs.bult.ai/guides/database



#### Build a Database Service

Deploy databases via templates (e.g., PostgreSQL, MongoDB) in Canvas UI.

Example:

1. Select “**PostgreSQL**” template.
2. Set compute size (**XS**) and volume (**0.5GB**).
3. Get connection string (e.g., postgres\://user:pass\@host:5432/db).

#### PostgreSQL

Deploy with automated backups and monitoring. Access via psql or Database View.

#### MySQL

Similar setup to PostgreSQL, with phpMyAdmin template for management.

#### Redis

Deploy for caching or queues. Example: redis\://host:6379.

#### MongoDB

Deploy with 1-click template. Access via MongoDB Compass or Database View.


# Deployments
Source: https://docs.bult.ai/guides/deployments



#### Pre-Deploy Command

Run commands before deployment (e.g., npm ci) in “**Git**” tab’s “**Build Settings**.”

#### Start Command

Override default start command (e.g., npm run start) for Nixpacks or Docker.

#### Deployment Actions

* **Deploy**: Trigger via Canvas UI’s “**Deploy Service**” button.
* **Pause**: Pause services to save resources.
* **Force Rebuild**: Rebuild without cache for updates.

#### GitHub Autodeploys

Enable auto-deploys on push to a branch (e.g., main). Configure in “**Git**” tab.

#### Optimize Performance

Use XS compute for prototypes, scale to M or L for production. Enable auto-scaling (Pro plan).


# Custom Domains
Source: https://docs.bult.ai/guides/domains



Manage custom domains in **app.bult.ai/domains** to expose services with branded URLs (e.g., blog.com).

Free tier supports 1 custom domain; Pro offers unlimited.

## **Step 1:**

* **Setup**:
  1. Go to "**Domains**" page - [app.bult.ai/domains](https://app.bult.ai/domains).
  2. Click “**Add Domain**”.

     <img alt="Screenshot 2025-12-15 at 12.35.34.png" />
  3. Enter domain: for example, **blog.com.**

     <img alt="Screenshot 2025-12-15 at 12.38.15.png" />
  4. Configure DNS with CNAME to auto-generated value (e.g., [gj7g3dvv.fin1.bult.app](http://gj7g3dvv.fin1.bult.app).).

     <img alt="Screenshot 2025-12-15 at 12.39.04.png" />
  5. Click “**Verify**” (DNS propagation may take 72 hours).
* **Status**:
  * **Not Verified**: DNS not propagated.
  * **Verified**: Ready to use.
* **Actions**:
  * **DNS Configuration**: View CNAME details.
  * **Delete Domain**: Irreversible; confirm in “Delete Domain” prompt.
* **Auto-Generated URLs**: Default URLs (e.g., [https://blog.fin1.bult.app](https://blog.fin1.bult.app)) provided for all services.
* **Security**: Automatic SSL for all domains (custom and auto-generated).
* **Limits**: Free tier: 1 custom domain. Pro: unlimited domains, prioritized DNS verification.

## **Step 2:**

1. Go to your project.
2. Select your service.
3. In "**Edit Service**" window, click "**Add Route**".

   <img alt="Screenshot 2025-12-15 at 12.43.46.png" />
4. Select your **domain** in the dropdown list.

   <img alt="Screenshot 2025-12-15 at 12.46.21.png" />
5. Click "**Add**".

<img alt="Screenshot 2025-12-15 at 12.48.14.png" />


# Foundations
Source: https://docs.bult.ai/guides/foundations



#### Workspaces

Create a workspace to group projects. Free tier allows 1 workspace with a custom name (e.g., “John’s Workspace”) and icon color (Green, Blue, etc.). Go to app.bult.ai, click “Create Workspace,” and set up in seconds.

#### Projects

Projects contain services (e.g., Node.js app, MongoDB). Free tier supports 5 projects. Create via +Create New Project, name it (e.g., “Project1”), and select Finland region (default).

#### Services

Services are apps or databases (e.g., Express.js, Redis). Add via Canvas UI’s “+Create” button, choosing GitHub repo or Docker image. Configure compute size (XS to 3XL) and instances (up to 2 on free tier).

#### Volumes

Add storage (up to 10GB on free tier) via Canvas UI. Example: Create a 0.5GB volume named fastened-volume for a PostgreSQL service. Pro plan supports up to 250GB.

#### Environment Variables

Set environment variables in Canvas UI’s “Environment” tab. Use Form View for key-value pairs (e.g., DATABASE\_URL=mongodb://...) or Raw Editor for .env files. Upload .env files for bulk updates.

### Routes

Expose services publicly or privately via routes in Canvas UI’s “General” tab. Basic plab supports 1 custom domain (e.g., [blog.com](http://blog.com)) and auto-generated URLs (e.g., [blog.fin1.bult.app](http://blog.fin1.bult.app)). Set path (e.g., /api) and port (e.g., 80); private networking auto-enables for internal access (e.g., [db.fin1.bult.app](http://db.fin1.bult.app)). Pro plan allows unlimited domains.


# Languages & Frameworks
Source: https://docs.bult.ai/guides/language-frameworks



Bult supports popular frameworks with 1-click templates or custom configs:

* **Node.js**: Express, Nest, Fastify, Sails
* **Python**: Flask, FastAPI, Django
* **Go**: Beego, Gin
* **Ruby**: Rails
* **Rust**: Axum, Rocket
* **PHP**: Laravel, Symfony
* **Clojure**: Luminus
* **Scala**: Play
* **Java**: Spring Boot
* **JavaScript/TypeScript**: Angular, React, Remix, Vue, Nuxt, SvelteKit, Solid, Astro
* **Elixir**: Phoenix, Phoenix Distillery

Example: Deploy Express.js

1. Select “GitHub Repository” in Canvas UI.
2. Enter [https://github.com/username/express-app](https://github.com/username/express-app).
3. Choose branch (e.g., main) and XS compute size.
4. Click “Create” to deploy to [https://express-app.fin1.bult.app](https://express-app.fin1.bult.app).


# MCP
Source: https://docs.bult.ai/guides/mcp



The **MCP Server** exposes platform capabilities through the Model Context Protocol (MCP), enabling AI agents and MCP-compatible clients to interact with Bult in a structured and secure way.

***

## Overview

The MCP Server acts as a bridge between platform and AI tools such as:

* Claude Desktop
* Cursor
* Any MCP-compatible agent framework

It allows agents to perform actions on Bult without direct integration complexity.

***

## Features

* Project lifecycle tools: list, inspect, create, update, delete, deploy, start, stop, and discard changes.
* Service management for daemon and database services, including Docker image and Git-based deployments.
* Persistent volumes, route/domain mappings, templates, service logs, and build history.
* MCP tool annotations for read-only, idempotent, and destructive operations where supported.
* Works over stdio with Claude Desktop, Claude Code, Cursor, Google Antigravity and other MCP-compatible clients.

***

## Installation

#### Requirements

* Node.js 18 or newer.
* Bult API token.

If you install the package globally, use the `bult-mcp` binary:

```shellscript theme={null}
npm install -g @bultcloud/mcp-server
bult-mcp
```

You can also run it with `npx` from MCP client configs:

```shellscript theme={null}
npx -y @bultcloud/mcp-server
```

***

## Configuration

The server reads its configuration from environment variables.

| **Variable**     | **Required** | **Description**                           |
| :--------------- | :----------- | :---------------------------------------- |
| `BULT_API_URL`   | Yes          | Bult API base URL, `https://api.bult.ai`. |
| `BULT_API_TOKEN` | Yes          | API token used for Bearer authentication. |

***

## MCP Integration

### Claude Desktop

Add the server to `claude_desktop_config.json`.

Using `npx`:

```json theme={null}
{
  "mcpServers": {
    "bult": {
      "command": "npx",
      "args": ["-y", "@bultcloud/mcp-server"],
      "env": {
        "BULT_API_URL": "https://api.bult.ai",
        "BULT_API_TOKEN": "your-token"
      }
    }
  }
}
```

### Claude Code

Using `npx`:

```text theme={null}
claude mcp add bult \
  -e BULT_API_URL=https://api.bult.ai \
  -e BULT_API_TOKEN=your-token \
  -- npx -y @bultcloud/mcp-server
```

### Codex CLI

Using `npx`:

```text theme={null}
codex mcp add \
  --env BULT_API_URL=https://api.bult.ai \
  --env BULT_API_TOKEN=your-token \
  bult \
  -- npx -y @bultcloud/mcp-server
```

***

## Available Tools

Refer to the [repository](https://github.com/bultcloud/mcp-server#available-tools) for currently available tools.

More tools will be added as the platform evolves.

***

## Contributing

Contributions are welcome. Please open issues or pull requests on GitHub:

[https://github.com/bultcloud/mcp-server](https://github.com/bultcloud/mcp-server)


# Monitoring
Source: https://docs.bult.ai/guides/monitoring



#### Logs

Access 7-day logs (Basic plan) or 30-day logs (Pro plan):

in Canvas UI’s “View logs” button:

<img alt="Screenshot 2025-08-07 at 19.27.19.png" />

or “View build logs” button in the "Edit Service" under "Builds":

<img alt="Screenshot 2025-08-07 at 19.22.22.png" />

#### Usage

Track CPU, RAM, and Volume usage in [app.bult.ai/usage](https://app.bult.ai/usage).

#### Service Metrics

View real-time metrics (e.g., response time, errors) in “View metrics” button.

<img alt="Screenshot 2025-08-07 at 19.25.49.png" />

Service Metrics window shows CPU Usage, Memory Usage, and Network I/O for a specific period of time:

<img alt="Screenshot 2025-08-07 at 19.25.31.png" />


# Networking
Source: https://docs.bult.ai/guides/networking



#### Public Networking

Expose services via auto-generated URLs (e.g., [https://project1.fin1.bult.app](https://project1.fin1.bult.app)). Add custom domains (e.g., blog.com) with CNAME to fin1.bult.app. Verify in [app.bult.ai/domains](https://app.bult.ai/domains).

#### Private Networking

Enable private communication between services (e.g., Express to MongoDB) without explicit links (August 2025 update). Ports auto-detected; edit in “General” tab.


# OpenClaw template
Source: https://docs.bult.ai/guides/open-claw



We are excited to announce that OpenClaw is now officially available in the [bult.ai](http://bult.ai) Templates library!

### **What is OpenClaw?**

OpenClaw is an open-source, autonomous AI agent framework designed to connect Large Language Models (LLMs) directly to your daily messaging apps. It acts as your personal AI assistant, capable of executing real-world tasks directly from your chat interface.

With OpenClaw, you can automate a wide variety of workflows, including:

* Use it as your personal assistant across all of the major platforms
* Generating personalized morning briefings
* Reviewing GitHub pull requests
* Assisting with academic research and writing

### **Why run OpenClaw on [bult.ai](http://bult.ai)?**

Deploying OpenClaw via [bult.ai](http://bult.ai) removes the friction of complex setups and local hosting. By using our preconfigured template, you gain several advantages:

* Pre-Configured Setup: Launch instantly with a ready-to-use, preconfigured environment.
* Persistent Memory: Your AI agent retains context and memory across conversations.
* Always-On Cloud Assistant: [bult.ai](http://bult.ai) hosts your agent in the cloud, allowing it to monitor your accounts 24/7 and execute tasks via messaging apps without requiring your personal computer to stay powered on.

### **Prerequisites & Configuration**

To successfully deploy the OpenClaw template, you will need to configure the following environment variables during setup.

Note: OpenClaw uses Telegram as its default messaging interface, but it can be configured to work with other platforms like Slack.

| Environment Variable     | Description & Instructions                                                                                                                                    |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| TELEGRAM\_BOT\_TOKEN     | The API token used to connect your agent to Telegram. You can generate this by messaging @BotFather directly on Telegram.                                     |
| OPENAI\_API\_KEY         | The API key for your chosen LLM provider. While OpenAI is used as an example, you can supply the API key for the specific model you wish to power your agent. |
| OPENCLAW\_GATEWAY\_TOKEN | A security token used to protect your gateway. You must generate a secure, random string consisting of exactly 32 characters for this value.                  |

Once these credentials are provided in your [bult.ai](http://bult.ai) deployment settings, your autonomous OpenClaw assistant will be live and ready to receive commands from your messaging app!


# Regions
Source: https://docs.bult.ai/guides/regions



Bult.ai deploys services in high-performance regions to ensure low latency. Currently, only Finland (Helsinki) is available, with more regions planned.

* **Current Region**:
  * **Finland, Helsinki**: Available now. Low-latency for European users. All projects deploy here by default (non-changeable in free tier).
* **Upcoming Regions** (Q3 2026):
  * **Germany, Frankfurt**: Central Europe expansion.
  * **USA, New York**: Optimized for North America.
  * **Singapore, Singapore**: High performance for Asia-Pacific.
* **Features**:
  * **Global CDN**: Edge delivery for fast performance worldwide (US, EU, India, etc.).
  * **Private Networking**: Auto-enabled for services in the same region (August 2025 update).
  * **Latency**: Helsinki offers \<50ms latency for EU users; new regions will reduce latency globally.
* **Limits**: Basic plan locks to Helsinki. Pro plan will allow region selection.
* **Best Practices**:
  * Deploy to Helsinki for optimal performance now.
  * Plan for multi-region deployments (Pro plan) to mitigate outages.
  * Check bult.instatus.com for region status.

**Example**: Deploy to Helsinki:

1. Create project in [app.bult.ai](https://app.bult.ai/).
2. Select Finland (default).
3. Deploy service; access via fin1.bult.app URL.


# Templates
Source: https://docs.bult.ai/guides/templates



#### Create

Build custom templates in Canvas UI. Example: Save a Node.js + MongoDB setup.

#### Best Practices

* Use minimal compute sizes (XS) for templates.
* Include default .env files for portability.
* Test templates with public repos for sharing.

#### Deploy

<u>Deploy</u> templates with 1 click. Example: Select “**WordPress**” and deploy instantly.

#### **Ready-to-use templates**

Bult.ai offers 12 pre-configured templates for instant deployment of apps and databases. Access via Canvas UI’s “**+Create**” > “**Templates**” menu. Templates optimize setup for indie devs and startups.

| Template               | Description                                    | Use Case                | Compute Size | Volume |
| :--------------------- | :--------------------------------------------- | :---------------------- | :----------- | :----- |
| MySQL                  | Relational database with phpMyAdmin support    | Web apps, CMS           | XS           | 0.5GB  |
| RabbitMQ               | Message queue for task processing              | Microservices, queues   | XS           | 0.5GB  |
| Gitea                  | Self-hosted Git server                         | Code hosting            | S            | 1GB    |
| Ghost CMS              | Modern blogging platform                       | Blogs, newsletters      | S            | 1GB    |
| PostgreSQL             | Production-ready relational database           | Data-heavy apps         | XS           | 0.5GB  |
| Redis                  | In-memory cache and queue                      | Caching, sessions       | XS           | 0.5GB  |
| MinIO Object Storage   | S3-compatible object storage                   | File storage, backups   | S            | 1GB    |
| WordPress              | Popular CMS for websites                       | Blogs, small businesses | S            | 1GB    |
| N8N                    | Workflow automation tool                       | App integrations        | S            | 1GB    |
| phpMyAdmin             | Web-based MySQL management                     | Database admin          | XS           | 0.5GB  |
| Elasticsearch + Kibana | Search and analytics engine with visualization | Log analysis, search    | M            | 2GB    |
| MongoDB                | NoSQL database for flexible data               | APIs, real-time apps    | XS           | 0.5GB  |

**Details**:

* **Deployment**: Select template in Canvas UI, configure compute (XS recommended), and deploy in \<30 seconds.
* **Customization**: Set environment variables (e.g., DATABASE\_URL) in “**Environment**” tab.
* **Volumes**: Auto-provisioned (e.g., 0.5GB for PostgreSQL). Basic plan: 2 volumes/project, 10GB total.
* **Monitoring**: View logs (7-day retention) and metrics in Canvas UI.
* **Sharing**: Create custom templates and share via marketplace (v3, October 2025).
* **Best Practices**:
  * Use XS compute for templates to maximize credits.
  * Enable backups for databases (e.g., PostgreSQL) via Cron Jobs (Pro plan).
  * Test templates with public repos for portability.

**Example**: Deploy WordPress:

1. Go to Canvas UI, click “**+Create**” > “**Templates**” > “**WordPress**.”
2. Set compute to S (0.2 vCPU, 0.5 GB RAM) and 1GB volume.
3. Deploy to [https://wordpress.fin1.bult.app](https://wordpress.fin1.bult.app).
4. Configure via wp-admin with auto-generated credentials.


# Terminal
Source: https://docs.bult.ai/guides/terminal



### Overview

The Terminal provides direct access to the running container of a deployed service. It enables developers to inspect processes, review files, execute commands, and perform debugging tasks without configuring SSH. Terminal sessions run inside the [Bult.ai](http://Bult.ai) interface and follow the platform’s security and isolation policies.

<img alt="terminal.png" />

### Accessing the Terminal

The Terminal can be opened from the service page of any active deployment. When a session starts, [Bult.ai](http://Bult.ai) establishes a secure connection to the container instance.\
No SSH keys, firewall rules, or additional configuration are required.

### Capabilities

The Terminal supports the following operations inside active containers:

* Inspect current processes and resource usage
* Navigate and edit files within the container file system
* Check environment variables and runtime configuration
* Test connectivity to external APIs, queues, or databases
* Run commands to monitor application behavior in real time
* Install temporary debugging tools (for example, curl or netcat)

All actions occur within a temporary session that does not require rebuilding or redeploying the service.

### Limitations

The Terminal does not persist installed packages or changes that require container rebuilds.\
Access is limited to running instances. If a service is stopped or fails before startup, the Terminal cannot be opened.

Be aware: changes introduced to the container's file system (except mounted volumes) will be lost after restart.

### Future Enhancements

Planned improvements include multi-instance access, session history, remote diagnostics, and automated recommendations powered by AI.


# Usage
Source: https://docs.bult.ai/guides/usage



Track resource consumption in [app.bult.ai/usage](https://app.bult.ai/usage) to manage costs and optimize performance. Basic plan includes \$5 credits; Pro plan offers higher limits.

* **Dashboard**: View CPU, RAM, and volume usage for a date range (e.g., Jul 24–28).
  * **CPU Usage**: Example: “blog (Project1)” on XS size, 21.12 hours, \$0.03.
  * **RAM Usage**: Example: “blog” on XS, 21.12 hours, \$0.04.
  * **Volume Usage**: Example: 0.5GB volume, \$0.04 monthly.
* **Billing**:
  * **Basic Plan**: \$5/mo + usage, start with \$5 free credits, 0.5 vCPU, 1GB RAM, 10GB volumes, 7-day logs.
  * **Pro Plan** (September 2025): \$20/mo + usage, up to 8 vCPU, 16GB RAM, 250GB volumes, 30-day logs.
  * **Payment**: Add funds via Stripe in app.bult.ai/billing. No payment method required for free tier.
  * **Cost Example**: XS compute (21.12 hours) + 0.5GB volume = \$0.11 total.
* **Limits**: Basic Plan: 5 projects, 5 services/project, 2 volumes/project. Pro: unlimited projects/services/volumes.
* **Optimization**:
  * Pause unused services to save credits.
  * Monitor usage to avoid exceeding free tier limits.
  * Use templates (e.g., PostgreSQL) to reduce setup costs.

**Example**: Check usage for “Project1”:

1. Go to [app.bult.ai/usage](https://app.bult.ai/usage).
2. Filter by date (e.g., Jul 24–28).
3. Review CPU (\$0.03), RAM (\$0.04), and volume (\$0.04) costs.


# Billing
Source: https://docs.bult.ai/reference/billing



## Billing Overview

Bult keeps billing clear: you pay the **subscription fee in advance**, and **usage charges are billed at the end of each monthly period**. Credits and included usage cover usage costs but do **not** apply to subscription fees.

### Plans & Compute Sizes

Bult offers several subscription plans along with different compute sizes. Each compute size has fixed resources and pricing.

#### Free Trial

* **Price:** \$0
* **Duration:** 7 days
* **Included:** One-time \$5 credits, applied only to usage charges.
* **Compute Size Available:**
  * **XS (Static Sites)** — 0.1 vCPU / 256 MB RAM — \$2.70 / month
  * **S (Small Apps)** — 0.25 vCPU / 512 MB RAM — \$5.40 / month
* **Volume Size Available:** 512MB
* **End of trial:**
  * Ends automatically after 7 days, or
  * Ends earlier if the \$5 trial credits are fully used. Deployments are paused unless you upgrade to a paid plan. On upgrade, remaining credits are carried over to the paid plan.

#### Starter

* **Price:** \$5 / month (paid up front at start of cycle)
* **Best for:** Developers moving into production workloads.
* **Compute Sizes Available:**
  * **M (Web Apps)** — 0.5 vCPU / 1 GB RAM — \$12.00 / month
  * **L (APIs)** — 1 vCPU / 2 GB RAM — \$24.00 / month
  * **XL (Databases)** — 2 vCPU / 4 GB RAM — \$48.00 / month
* **Volume Size Available:** Up to 50GB
* **Included usage:** \$5 worth of usage covered each month (non-accumulative, resets each cycle).

#### Pro *(coming soon)*

* **Price:** \$20 / month (paid up front at start of cycle)
* **Best for:** Teams or heavier users needing larger compute and collaboration features.
* **Compute Sizes Planned:**
  * **2XL (High Traffic)** — 4 vCPU / 8 GB RAM — \$96.00 / month
  * **3XL (Enterprise)** — 8 vCPU / 16 GB RAM — \$192.00 / month
* **Volume Size Planned:** Up to 250GB
* **Included usage:** \$20 worth of usage covered each month (non-accumulative, resets each cycle).

***

### Plan Comparison

| Plan         | Subscription Fee             | Included Usage Coverage           | Duration |
| ------------ | ---------------------------- | --------------------------------- | -------- |
| Free Trial   | \$0                          | One-time \$5 credits (usage only) | 7 days   |
| Starter      | \$5 / month (paid up front)  | \$5 usage / month                 | Monthly  |
| Pro *(soon)* | \$20 / month (paid up front) | \$20 usage / month                | Monthly  |

***

### Compute Sizes Reference

Here are the compute sizes you can pick from, and their pricing:

| Compute Size     | vCPU | RAM    | Monthly Cost  |
| ---------------- | ---- | ------ | ------------- |
| XS Static Sites  | 0.1  | 256 MB | \$2.70 / mo   |
| S Small Apps     | 0.25 | 512 MB | \$5.40 / mo   |
| M Web Apps       | 0.5  | 1 GB   | \$12.00 / mo  |
| L APIs           | 1    | 2 GB   | \$24.00 / mo  |
| XL Databases     | 2    | 4 GB   | \$48.00 / mo  |
| 2XL High Traffic | 4    | 8 GB   | \$96.00 / mo  |
| 3XL Enterprise   | 8    | 16 GB  | \$192.00 / mo |

***

### Credits

* Every new account starts with **\$5 free credits** during the trial.
* Credits apply **only to usage charges**, not to subscription fees.
* If trial credits are used up, deployments will stop unless you upgrade to a paid plan.
* Unused trial credits carry over when upgrading.
* Credits are **non-refundable** once used.

***

### Usage

* Usage includes computes (CPU / RAM) and storage.
* Paid plans include usage coverage equal to the plan’s subscription fee, which resets every cycle.
* Usage charges above the included coverage are billed at the **end of the month**.
* To protect against extreme usage, occasional mid-cycle invoices may be issued when usage grows unusually high.

#### Example 1: Free Trial Credits Exhausted

* During trial you use consume all trial **\$5** in usage.
* Trial ends and deployments stop unless upgraded.

#### Example 2: Usage Below Included Coverage

* You are on Starter plan (\$5/month) with \$5 included usage.
* You use **\$2.70** in usage.
* That usage is fully covered. The leftover \$2.30 of included usage is waived for that cycle.
* You pay only the **\$5** subscription fee.

#### Example 3: Usage Above Included Coverage

* You are on Starter plan (\$5/month) with \$5 included usage.
* Usage = **\$7.00**.
* First \$5 covered, \$2 billed in usage.
* Total you pay **\$5** for subscription fee and **\$2** for extra usage.

***

### Refunds

* Contact [team@bult.ai](mailto:team@bult.ai) within **14 days** of the charge.


# Community
Source: https://docs.bult.ai/reference/community



Join our [Discord](https://discord.gg/cet2ZPv2yJ), follow on [X](https://x.com/bultdev), watch on [YouTube](https://www.youtube.com/@bultdev), or contribute new teamplates on [GitHub](https://github.com/bultcloud).

Share feedback at [team@bult.ai](mailto:team@bult.ai).


# Migration
Source: https://docs.bult.ai/reference/migration



#### Docker Compose

####

#### Migrate from other paltforms

Replicate services in Canvas UI. Use Docker for custom setups.

### Request help

Contact our team via [team@bult.ai](mailto:team@bult.ai) or [Discord channel](https://discord.gg/cet2ZPv2yJ) so we can help you migrate from other platforms to Bult.ai.


# Support
Source: https://docs.bult.ai/reference/support



Bult offers multiple support channels to ensure you succeed:

* **Chat Support**: Access via [app.bult.ai](https://app.bult.ai/)’s “**AI Support Chat**” button. Available for all users.
* **Email**: Contact [team@bult.ai](mailto:team@bult.ai) for technical or billing queries. Basic plan users get standard support; Pro plan (coming soon) includes priority support (1-day response).
* **Discord Community**: Join [discord.gg/cet2ZPv2yJ](https://discord.gg/cet2ZPv2yJ) for peer support, tips, and direct interaction with our team. Ideal for quick questions or feedback.

  <img alt="Screenshot 2025-08-07 at 19.37.32.png" />
* **Documentation**: This guide at [docs.bult.ai](https://docs.bult.ai/) covers setup, troubleshooting, and advanced usage. Searchable via navigation.

  <img alt="Screenshot 2025-08-07 at 19.31.36.png" />
* **Status Page**: Check system status at [bult.instatus.com](https://bult.instatus.com/) for real-time updates on uptime and incidents.

  <img alt="Screenshot 2025-08-07 at 19.30.59.png" />
* **Enterprise Support**: Custom SLAs and dedicated support for Startups and Enterprise plans. Contact [team@bult.ai](mailto:team@bult.ai).

**Tips**:

* Include project/workspace names and email in support requests for faster resolution.
* Check Errors for common issues (e.g., “Application Failed to Respond”).


# OpenClaw tutorial
Source: https://docs.bult.ai/tutorials/open-claw-tutorial



**How to set up morning briefings on OpenClaw in [Bult.ai](http://Bult.ai)**

Use OpenClaw on Bult to create a personal morning briefer that sends you a concise daily update.

A morning briefer is a lightweight AI assistant workflow that checks the most important things you care about before your workday starts and delivers them in one message.

Instead of opening multiple apps every morning, you get one structured briefing that helps you quickly understand whatever matters most to you.

**1. Deploy the template**

First, deploy the OpenClaw template on Bult.ai:

* Go to your project → Click Create → Select Templates → Select OpenClaw

<Frame>
  <img alt="Screenshot 2026 04 23 At 11 37 53" />
</Frame>

* Click Apply

<Frame>
  <img alt="Screenshot 2026 04 23 At 11 38 00" />
</Frame>

Then *Edit Service* by clicking on the *openclawbultai* service → and go to Environment tab:

<Frame>
  <img alt="Screenshot 2026 04 23 At 11 41 05" />
</Frame>

Then fill out these required environment variables (values):

• OPENAI\_API\_KEY

• OPENCLAW\_GATEWAY\_TOKEN

• TELEGRAM\_BOT\_TOKEN - add this new variable there

**2. Make the initial introduction**

After deployment, start chatting with the bot and make your initial introduction so it can learn who you are and how you want it to help you.

**3. Add calendar access**

The easiest way is to use a read-only Google Calendar ICS feed.

This allows the assistant to check your schedule without needing full access to your Google account.

Important note: A private ICS link should be treated like a secret. Do not share it publicly.\\

**4. Prompt the assistant**

After that, you can send a prompt like this:

***Daily Morning Briefing Setup***

Set up a daily morning briefing for me. Send it every day at 7:00 AM on Telegram.

The briefing should be concise, informational, easy to scan, and useful for starting my day. Do not add fluff or overly long commentary. Include links for the articles.

I want the briefing to include these sections:

**1. Calendar**

* Check my schedule for today
* Show today’s meetings and events clearly
* If there are no events, say that the day looks clear

**2. Weather**

* Show the current weather and today’s forecast for Astana
* Mention anything that could affect my day

**3. Local news**

* Include important Astana and Kazakhstan news that might affect me directly or indirectly
* Focus on practical relevance, not random general news

**4. AI / ML news**

* Include the most important updates in AI and machine learning
* Prioritize high-signal developments, product launches, regulation, major partnerships, and adoption trends

**5. Cybersecurity news**

* Include important cybersecurity developments, breaches, threats, platform security issues, and anything relevant to Central Asia or Kazakhstan when available

**6. Finance news**

* Include useful finance news, especially related to stocks, markets, macro trends, and investment opportunities\
  The result will look like this:
  <Frame>
    <img alt="Kar 1" />
  </Frame>

This is only of infinite ways you can utilize OpenClaw. Whatever automation you might need, could be done with OpenClaw.


# n8n automation
Source: https://docs.bult.ai/tutorials/tutorial-n8n

How to Deploy an n8n Template on Bult.ai and Build a Telegram AI Assistant with Gmail, Google Tasks, and Google Contacts

### Overview

Automation tools like n8n make it easy to connect apps and AI models into a single assistant that manages your daily work. Combined with [Bult.ai](http://Bult.ai), you can deploy n8n in minutes, link it to Telegram, Gmail, Google Tasks, Google Contacts, and Calendar, and have your own personal AI secretary running in the cloud.

This updated guide uses the [******official Bult.ai n8n workflow repository******](http://Bult.ai) instead of the older template library, giving you more features and better defaults.

<iframe title="YouTube video player" />

### Step 1: Deploy n8n on [**Bult.ai**](http://Bult.ai)

1. Sign up at [<u>bult.ai</u>](http://bult.ai).
2. Go to your dashboard → click **New Project**.
3. Give it a name and **open the project**.
4. Click **Create**, then go to **Templates → n8n**.
5. Click **Apply**, then **Deploy**.
6. Once deployed, you’ll see a public link like: [https://your-project-name.fin1.bult.app/](https://your-project-name.fin1.bult.app/)
7. Follow that link, sign up for n8n, click **Send activation link**, check your email, copy the code, go to **Plan & Usage**, and paste it.

Now your cloud n8n editor is live.

### **Step 2: Import the Workflow**

You can start from scratch or import a ready-made workflow. You can find many Workflow Templates [<u>here</u>](https://n8n.io/workflows/).

1. In this example I will use Personal Telegram Assistant Bot from this [<u>GitHub repo</u>](https://github.com/bultcloud/n8n-workflows). Open the repository and copy the contents of bult-assistant.json.
2. In your n8n, click Create Workflow and paste the template (Ctrl+V).

Now your workflow listens for Telegram messages.\
If you send **text**, it goes straight to ChatGPT.\
If you send **voice**, it’s transcribed to text first.\
The AI model decides whether to check Gmail, Google Tasks, Google Contacts, or Calendar — then replies to you directly on Telegram.

### **Step 3: Connect Telegram**

Now we need to set up credentials.

1. Open **Telegram** and search for **@BotFather**.
2. Send `/start`and then `/newbot` and follow the setup.
3. Copy the **API token** BotFather gives you.
4. In n8n, open the **Telegram Trigger** node and paste the token into a new Telegram credential.

That connects your bot to n8n.

### **Step 4: Connect Google Services**

1. In n8n, open a **Gmail** node and create a new credential.
2. Copy the **Redirect URI** shown in n8n (it will look like your Bult URL + `/rest/oauth2-credential/callback`).
3. Go to [<u>Google Cloud Console.</u>](https://console.cloud.google.com/)\
   • Create a **new project**.\
   • Go to **APIs & Services → OAuth Consent Screen** and fill the required info.\
   • Click **Create OAuth Client ID** → choose **Web Application**.\
   • Go to **Credentials** → copy the **Client ID** and **Client Secret**, then paste them into n8n.\
   • Click **Connect**, sign in with Google, and approve.
4. Go to Clients, pick your Client ID. Copy and paste Client ID and Client Secret from Google Cloud to N8N.
5. Click **Connect**, sign in with your Google account, and approve the permissions. Repeat the same for ****Google Calendar, Google Tasks and Google Contacts (Google People API).****
6. In Google Cloud, type Gmail, Calendar, Tasks and Google People in the search bar and enable their APIs.

### **Step 5: Test the bot (text and voice)**

Open your Telegram bot → tap **Start**. In n8n click **Execute Workflow** (for testing). Send a message:

* Text: “What tasks do I have today?”, “What events do I have today?”, “When do they end?”, “What emails did I receive yesterday?”
* Voice: speak the same prompts; the flow transcribes, routes to Gmail/Tasks/Contacts/Calendar, and replies.

If replies look good, switch the workflow to **Active** so it answers automatically without pressing Execute.

<img alt="1_HKw2UC4V2ULcaQvvgIMwtg.webp" />

### **Conclusion**

This workflow shows how easily you can automate daily routines using n8n. Once deployed on Bult, you can extend or modify it to fit your own needs.

For example, you can add Google Sheets node and work with them through the Telegram Chat. N8N gives you full flexibility to connect tools, trigger actions, and create your own assistant for any workflow.

### **Links**

* [GitHub repo](https://github.com/bultcloud/n8n-workflows)
* [Youtube step-by-step tutorial](https://youtu.be/0iKt4KVC38w?si=9OnasutDGD3saI4X)


# RAG template project
Source: https://docs.bult.ai/tutorials/tutorial-rag



### Overview

Deploy a production ready Retrieval Augmented Generation (RAG) system in minutes.

<iframe title="YouTube video player" />

Full step-by-step video tutorial is here: [<u>https://youtu.be/CkcVGtiSGDQ?si=Y1X1LP-Aw09g\_zIp</u>](https://youtu.be/CkcVGtiSGDQ?si=Y1X1LP-Aw09g_zIp)

**GitHub repo**: [https://github.com/bultcloud/RAG-BultAI](https://github.com/bultcloud/RAG-BultAI)

Upload documents. Ask questions. Get answers with inline citations and source scoring.

This template includes:

• Hybrid search combining keyword and vector retrieval\
• Cross encoder reranking for higher precision\
• Multi model LLM support\
• Background document processing\
• Authentication and analytics

It supports multiple LLM providers (OpenAI, Anthropic, Google, Ollama), hybrid search with reranking, OCR for scanned PDFs, multi-user authentication, and conversation export.

It is designed to demonstrate how to run serious AI workloads on [Bult.ai](https://bult.ai/) without managing infrastructure.

***

### Architecture

\#1

<Frame>
  <img alt="Rag 2" />
</Frame>

\#2

<Frame>
  <img alt="Rag 3" />
</Frame>

***

### Components

\
**App Service**\
FastAPI backend handling authentication, API endpoints, streaming responses.

**PostgreSQL**\
Stores users, projects, documents, analytics.

**pgvector**\
Stores embeddings and enables vector similarity search.

**Background Worker**\
Processes documents asynchronously:\
• Chunking\
• Embedding generation\
• OCR if needed

**LLM Provider**\
OpenAI, Anthropic, Google, or Ollama.

***

### Features

* Multi-model LLM support -- switch between OpenAI, Anthropic, Google AI, or local Ollama models via environment variable
* Advanced RAG pipeline -- hybrid search (BM25 + vector), cross-encoder reranking, HyDE query transformation, multi-query retrieval, query decomposition
* Document processing -- PDF, DOCX, PPTX, TXT, MD, CSV, JSON, HTML; automatic OCR for scanned PDFs via Tesseract
* Inline citations -- every response cites source documents with relevance scores
* Authentication -- JWT login/register + optional Google OAuth
* Analytics dashboard -- usage metrics, cost tracking, query latency, top projects
* Conversation export -- Markdown, JSON, and PDF export with full Unicode support
* Background processing -- async job queue with progress tracking and retry logic
* Single-page frontend -- clean UI with streaming responses, markdown rendering, dark mode

***

### Deploy RAG on bult.ai

[Bult.ai](https://bult.ai/) is a PaaS that deploys from GitHub with built-in database templates and Docker support.

You need three services: the app (GitHub), a PostgreSQL database, and a pgvector instance.

#### Prerequisites

* GitHub account
* OpenAI API key (get one here)
* [Bult.ai](https://bult.ai/) account

#### Step 1: Fork or clone this repository

Fork this repo on GitHub (or clone it and push to your own repo).

**GitHub repo**: [https://github.com/bultcloud/RAG-BultAI](https://github.com/bultcloud/RAG-BultAI)

#### Step 2: Create the app service (GitHub)

1. On bult.ai, click Create > GitHub
2. Select your forked repository
3. Go to the Git tab and change build settings from Nixpacks to Dockerfile. Set Dockerfile Path to Dockerfile and Dockerfile Context to "."
4. Inside the service settings, set the port to 8002
5. Go to Environment Variables and add the variables from .env.example.

The required ones:

| Variable         | Value                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------- |
| PG\_CONN         | postgresql://YOUR\_USER:YOUR\_PASSWORD @pgvector:5432/YOUR\_DB                            |
| OPENAI\_API\_KEY | Your OpenAI API key                                                                       |
| JWT\_SECRET      | A random string (generate: python -c "import secrets; print(secrets.token\_urlsafe(32))") |

Add any other settings from .env.example as needed (LLM\_MODEL, EMBEDDING\_MODEL, etc.).

Note: The PG\_CONN hostname must match the name of your pgvector Docker service (step 4).

Set the user, password, and database name to match your Postgres service (step 3).

#### Step 3: Create the PostgreSQL database

1. Click Create > in the list of services, go to Databases > Postgres
2. This creates a Postgres instance from a built-in template -- it's automated
3. The only thing you need to configure is the environment variables:

| Variable           | Value                                   |
| ------------------ | --------------------------------------- |
| POSTGRES\_USER     | Your database username (e.g., pgvector) |
| POSTGRES\_PASSWORD | A strong password                       |
| POSTGRES\_DB       | Your database name (e.g., ragdb)        |

These values must match what you put in PG\_CONN in step 2.

#### Step 4: Create the pgvector service (Docker)

The app needs the pgvector extension for vector search. Create a Docker service for it:

1. Click Create > Docker
2. Docker image: ankane/pgvector:latest
3. Name this service to match the hostname in your PG\_CONN (e.g., pgvector)
4. Deploy the service
5. After it's running, add a volume mounted at /var/lib/postgresql/data for persistent storage
6. Add internal port 5432

#### Step 5: Deploy and verify

1. All three services should show as running

<Frame>
  <img alt="1" />
</Frame>

2. Check the app service logs -- you should see database migrations and the worker starting
3. Open the public URL for your app service. Register a user and start chatting.

#### Troubleshooting

| Problem                     | Fix                                                                                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Database connection error   | Verify PG\_CONN hostname matches your pgvector service name. Check that POSTGRES\_USER, POSTGRES\_PASSWORD, and POSTGRES\_DB match across services. |
| Documents stuck in "queued" | Check app logs for errors. Verify OPENAI\_API\_KEY is set correctly.                                                                                |
| OCR not working             | Nixpacks installs Tesseract automatically from nixpacks.toml. Check build logs.                                                                     |
| Build fails                 | Make sure your fork is up to date. Check build logs on bult.ai.                                                                                     |

#### Optional: Google Sign-In

To enable Google OAuth login:

1. Go to Google Cloud Console and create a project (or use an existing one)
2. Navigate to APIs & Services > OAuth Consent Screen and configure it
3. Go to Credentials > Create OAuth Client ID > Web Application
4. Under Authorized redirect URIs, add your bult.ai callback URL. The format is:

```text theme={null}
https://<your-project>.<region>.bult.app/api/auth/google/callback
```

For example: [https://rag-bultai-raga-season.fin1.bult.app/api/auth/google/callback](https://rag-bultai-raga-season.fin1.bult.app/api/auth/google/callback)

Important: The redirect URI in Google Cloud Console must exactly match your app's public URL on bult.ai. You can find this URL in your app service settings on the bult.ai dashboard.

5. Copy the Client ID and Client Secret, then add these environment variables to your app service:

| Variable               | Value                                                                |
| ---------------------- | -------------------------------------------------------------------- |
| GOOGLE\_CLIENT\_ID     | Your OAuth client ID                                                 |
| GOOGLE\_CLIENT\_SECRET | Your OAuth client secret                                             |
| OAUTH\_REDIRECT\_URI   | https\://\<your-project>.\<region>.bult.app/api/auth/google/callback |

6. Redeploy. The login page will show a "Sign in with Google" button.

***

### Local Development

#### Prerequisites

* Python 3.10+
* PostgreSQL 14+ with pgvector extension
* OpenAI API key

#### Setup

```text theme={null}
# Clone your fork
git clone https://github.com/YOUR_USERNAME/rag-template-multimodel.git
cd rag-template-multimodel

# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up database
createdb ragdb
psql -d ragdb -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Schema is created automatically on first app startup

# Configure environment
cp .env.example .env

# Edit .env -- set OPENAI_API_KEY and PG_CONN at minimum

# Run
python app.py
```

A background worker starts automatically with the app. To run additional workers for faster document processing, open a separate terminal:

```text theme={null}
python core/worker.py
```

Open [http://localhost:8002](http://localhost:8002). Register a user and start uploading documents.

***

### How It Works

#### Document processing pipeline

1. User uploads a file through the web UI
2. A background job is created (status: queued)
3. The worker picks up the job and processes the document:

* Loads the file with PyMuPDF (PDFs) or LlamaIndex readers (other formats)
* Detects if the PDF has a text layer -- if not, runs OCR (Tesseract)
* Optionally extracts tables with pdfplumber
* Splits text into chunks (semantic or fixed-size, configurable)
* Generates embeddings via OpenAI API
* Stores chunks + embeddings in PostgreSQL with pgvector

4. Document status updates in real time: queued > processing > ready

#### Query pipeline

1. User asks a question in a conversation
2. The query goes through optional transformations: HyDE, multi-query expansion, decomposition
3. Hybrid search combines BM25 keyword matching + vector similarity (configurable alpha balance)
4. Cross-encoder reranks the top candidates for precision
5. Top chunks are sent to the LLM with a system prompt that enforces inline citations
6. Response streams back to the UI character by character

Uploading files:

<Frame>
  <img alt="3" />
</Frame>

Document stats:

<Frame>
  <img alt="4" />
</Frame>

***

### Configuration

All settings are controlled through environment variables. Copy .env.example to .env and adjust as needed.

#### Required

| Variable         | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| PG\_CONN         | PostgreSQL connection string (host must match your pgvector service) |
| OPENAI\_API\_KEY | OpenAI API key (used for embeddings and as default LLM)              |
| JWT\_SECRET      | Random string for signing authentication tokens                      |

#### LLM provider

| Variable            | Default                                          | Description                                         |
| ------------------- | ------------------------------------------------ | --------------------------------------------------- |
| LLM\_PROVIDER       | openai                                           | openai, anthropic, google, or ollama                |
| LLM\_MODEL          | gpt-4o-mini                                      | Model name (e.g., gpt-4o, claude-sonnet-4-20250514) |
| ANTHROPIC\_API\_KEY | -                                                | Required if LLM\_PROVIDER=anthropic                 |
| GOOGLE\_API\_KEY    | -                                                | Required if LLM\_PROVIDER=google                    |
| OLLAMA\_BASE\_URL   | [http://localhost:11434](http://localhost:11434) | Ollama server URL)                                  |

#### RAG tuning

These have sensible defaults and don't need to be set unless you want to experiment:

| Variable                | Default | What it does                                            |
| ----------------------- | ------- | ------------------------------------------------------- |
| HYBRID\_SEARCH\_ALPHA   | 0.5     | 0 = keyword only, 1 = vector only                       |
| USE\_RERANKING          | true    | Cross-encoder reranking for better precision            |
| USE\_SEMANTIC\_CHUNKING | true    | Chunk at topic boundaries instead of fixed token counts |
| USE\_HYDE               | false   | Generate hypothetical answer for retrieval              |

***

### Project Structure

```text theme={null}
rag-template-multimodel/
|-- app.py # FastAPI entry point, all endpoints, DB bootstrap
|-- core/
| |-- config.py # Environment-driven configuration
| |-- db.py # PostgreSQL connection pool
| |-- auth.py # JWT authentication, user registration/login
| |-- oauth.py # Google OAuth2 integration
| |-- tasks.py # Document processing: load, chunk, embed, OCR
| |-- retrieval.py # RAG pipeline: hybrid search, reranking, HyDE
| |-- export.py # Conversation export (Markdown, JSON, PDF)
| |-- worker.py # Background worker logic
| +-- logging_config.py # Structured logging setup
|-- providers/
| |-- base.py # Abstract LLM/embedding provider interface
| |-- registry.py # Provider auto-detection and registration
| |-- llm_openai.py # OpenAI LLM provider
| |-- llm_anthropic.py # Anthropic LLM provider
| |-- llm_ollama.py # Ollama LLM provider
| +-- embedder_openai.py # OpenAI embedding provider
|-- scripts/
| +-- create_admin.py # Create admin user from CLI
|-- static/
| +-- index.html # Single-page frontend
|-- Dockerfile # Docker image with OCR dependencies
|-- nixpacks.toml # Nixpacks config (used by bult.ai)
|-- requirements.txt # Python dependencies
+-- .env.example # Environment variable template
```

***

### API Reference

All endpoints except /api/health and /api/auth/ require a JWT token in the Authorization: Bearer \<token> header.

#### Authentication

```text theme={null}
POST /api/auth/register -- Create account (email + password)
POST /api/auth/login -- Get JWT token
GET /api/auth/me -- Get current user info
GET /api/auth/google -- Start Google OAuth flow (if configured)
```

#### Projects & Documents

```text theme={null}
GET /api/projects -- List user's projects
POST /api/projects -- Create project
DELETE /api/projects/{id} -- Delete project and all its data
POST /api/upload -- Upload document to project
DELETE /api/documents/batch -- Delete multiple documents
GET /api/projects/{id}/documents -- List documents in project
```

#### Chat

```text theme={null}
GET /api/projects/{id}/conversations -- List conversations
POST /api/projects/{id}/conversations -- Create conversation
POST /api/chat -- Send message (SSE streaming response)
GET /api/conversations/{id}/export?format=md -- Export conversation (md|json|pdf)
```

#### Analytics

```text theme={null}
GET /api/analytics -- Usage stats, query history, top documents
```

<Frame>
  <img alt="2" />
</Frame>

#### System

```text theme={null}
GET /api/health -- Health check (no auth required)
GET /api/jobs/{id}/progress -- Job processing progress
```

***

### Example: Send Chat Message

Request:

`POST /api/chat`

`{\
"project_id": 1,\
"conversation_id": 12,\
"message": "Summarize section 3 of the contract"\
}`

Headers:

Authorization: `Bearer <your_jwt_token>`

Response:\
Server Sent Events stream with incremental tokens.

***

### Customization

#### Change LLM provider

Set LLM\_PROVIDER and the corresponding API key in .env:

```text theme={null}
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
LLM_MODEL=claude-sonnet-4-20250514
```

#### Customize the system prompt

Edit SYSTEM\_PROMPT in core/config.py to change how the LLM responds -- citation style, tone, response structure, etc.

#### Change the UI theme

Edit CSS variables in static/index.html. The UI supports light and dark mode.

***

### Default Retrieval Configuration

* Embedding model: text-embedding-3-large
* Embedding dimension: 3072
* Chunk size: 1024 tokens
* Chunk overlap: 200 tokens
* Top K before reranking: 50
* Top K after reranking: 8
* Hybrid search alpha: 0.5