# The AI Chat
Source: https://docs.vybe.build/building-apps/ai-chat
How to communicate with the AI agent to build, modify, and understand your app
The AI chat is the primary way you interact with Vybe. Instead of writing code manually, you describe what you want in plain language, and the AI builds it for you.
***
## Sending messages
Type your message in the chat panel and press **Enter** or click the send button. The AI reads your message, plans its approach, and starts working on your app immediately.
You can send messages at any time — when creating a new feature, fixing a bug, asking a question, or requesting a design change. The AI maintains context from your entire conversation history within the current thread.
***
## What the AI can do
The AI agent has over 40 specialized tools at its disposal. Here is what it can do in your app:
| Capability | Description |
| ------------------------ | ------------------------------------------------------------------------------ |
| **Create files** | Generate new pages, components, API routes, and utility files |
| **Edit files** | Modify existing code with surgical precision — full rewrites or targeted edits |
| **Delete files** | Remove files that are no longer needed |
| **Search code** | Find specific patterns, functions, or references across your codebase |
| **Run SQL queries** | Execute queries against your app's built-in PostgreSQL database |
| **Install packages** | Add pre-approved npm packages to your project |
| **Connect integrations** | Wire up services like Slack, Jira, Salesforce, Stripe, and more |
| **Generate API clients** | Create typed client code from OpenAPI specifications |
| **Run type checks** | Validate TypeScript types across your project |
| **Run tests** | Execute test suites to verify your app works correctly |
| **Read logs** | Check development server logs for debugging |
| **Copy components** | Use pre-built Shadcn UI component patterns |
***
## Agent mode vs. Ask mode
Vybe offers two interaction modes, selectable from the mode toggle in the chat panel.
### Agent mode (default)
In Agent mode, the AI can read and modify your app. It creates files, edits code, runs database queries, installs packages, and connects integrations. This is the mode you use for building and iterating on your app.
### Ask mode
In Ask mode, the AI operates in read-only. It can read your files and answer questions about your code, but it cannot make any changes. Use Ask mode when you want to:
* Understand how a specific part of your app works
* Get explanations of code the AI previously generated
* Ask architecture or design questions without risking accidental modifications
* Review logic before deciding what to change
Switch to Ask mode when you want to explore and understand your app without triggering any code changes. Switch back to Agent mode when you are ready to build.
***
## Attaching images
You can attach images and screenshots to your messages. This is useful for:
* **Showing a desired design** — Attach a mockup or screenshot of a UI you want the AI to replicate
* **Reporting errors** — Screenshot an error in your browser and send it to the AI for debugging
* **Referencing layouts** — Share screenshots of existing tools or dashboards you want to recreate
Click the attachment icon in the chat input or paste an image directly from your clipboard.
***
## Clarifying questions
When the AI needs more information to proceed, it asks clarifying questions through interactive forms. Instead of guessing, the AI presents you with options to choose from or fields to fill in.
For example, if you ask the AI to "add a chart", it might ask:
* What data should the chart display?
* What chart type do you prefer (bar, line, pie)?
* Should it pull data from the database or an integration?
Answer the questions and the AI continues building with your input.
***
## Streaming responses
The AI streams its work in real-time. As it generates code, you can see:
* The AI's reasoning and plan of action
* Each file being created or modified
* Database queries being executed
* The live preview updating as changes are applied
You do not need to wait for the AI to finish before reviewing its work. The preview updates continuously as the AI writes code.
***
## Thread management
Each app can have multiple conversation threads. Threads let you organize different workstreams or features independently.
* **Create a new thread** to start a fresh conversation without losing previous context
* **Switch between threads** to pick up where you left off on a different task
* Each thread maintains its own conversation history
* The AI reads the full history of the active thread when responding
Changes made by the AI apply to the app regardless of which thread initiated them. Threads organize your conversations, not your code.
***
## Auto-suggestions
After the AI completes a task, it suggests next features or improvements you might want to build. These suggestions appear as clickable prompts below the AI's response.
Suggestions are contextual — they are based on what you just built and what would logically come next. You can click a suggestion to send it as your next message, or ignore them and type your own prompt.
***
## Example prompts
Here are effective prompts for common tasks:
**Building a dashboard**
> Build a dashboard that shows our sales pipeline from Salesforce with filtering by stage and date range.
**Adding database features**
> Add a new page that lets users search and filter our PostgreSQL customer database.
**Connecting integrations**
> Connect to our Jira project and create a view that shows all open bugs assigned to the current team.
**Improving UI**
> Redesign the customers table to use alternating row colors, add pagination with 25 rows per page, and make the email column clickable.
**Debugging**
> The chart on the analytics page is not loading. Check the API route and fix any issues.
**Adding new pages**
> Create a settings page where users can update their notification preferences and timezone.
***
## Tips for effective prompting
* **Be specific** — "Add a sortable table with columns for name, email, status, and created date" is better than "add a table"
* **Mention data sources** — Tell the AI where data should come from (database, integration, or hardcoded)
* **Describe the layout** — Mention how you want elements arranged on the page
* **Iterate in small steps** — Build one feature at a time rather than requesting everything in a single prompt
* **Reference existing pages** — "Make this page look like the customers page" helps the AI match your existing style
For more detailed prompting strategies, see [Prompting Tips](/tips/prompting).
***
## What's next
* Choose the right AI model for your task: [Choosing a Model](/building-apps/choosing-a-model)
* Understand the editor layout: [The Editor](/getting-started/interface)
* Learn about the live preview: [Preview & Sandbox](/building-apps/preview-and-sandbox)
# Choosing an AI Model
Source: https://docs.vybe.build/building-apps/choosing-a-model
Pick the right AI model for your task — from quick edits to complex architecture decisions
Vybe supports multiple AI models from Anthropic, OpenAI, and Google. Each model has different strengths, speed characteristics, and credit costs. You can switch models at any time without losing your conversation history.
***
## Available models
| Model | Provider | Reasoning | Best For |
| ---------------------- | --------- | --------- | ----------------------------------------------------------- |
| **Opus 4.5** (default) | Anthropic | Medium | General app building, complex logic |
| **Opus 4.5 - High** | Anthropic | High | Complex architectural decisions, debugging difficult issues |
| **Sonnet 4.5** | Anthropic | Standard | Faster responses, straightforward changes |
| **Haiku 4.5** | Anthropic | Standard | Quick edits, simple questions |
| **GPT-5.1** | OpenAI | Medium | Alternative perspective, specific strengths |
| **GPT-5.1 - High** | OpenAI | High | Complex reasoning with GPT |
| **Gemini 3 Pro** | Google | Standard | Alternative option, different approach |
***
## How to switch models
Click the **model selector** in the chat panel. A dropdown shows all available models. Select the model you want, and your next message will use it.
* Your model selection persists across sessions until you change it
* Switching models does not clear your conversation history
* The AI picks up right where the previous model left off
***
## Understanding reasoning effort
Some models offer configurable reasoning effort levels. Higher reasoning means the model spends more time thinking through complex problems before responding.
| Reasoning Level | Behavior | Credit Cost |
| --------------- | ------------------------------------------------------------ | ----------- |
| **Standard** | Normal processing — good for most tasks | Lowest |
| **Medium** | Extended reasoning — better for multi-step logic | Moderate |
| **High** | Deep reasoning — best for complex architecture and debugging | Highest |
Models with "High" in their name (like Opus 4.5 - High) use high reasoning effort by default. Standard models use their default reasoning level.
***
## When to use which model
The default model and the best all-around choice. Use Opus 4.5 for:
* Building new features from scratch
* Writing complex business logic
* Creating multi-page applications
* Working with integrations and databases
* Most day-to-day app development
This is the recommended model for the majority of your work.
The same model with higher reasoning effort. Use this when:
* Debugging issues that Opus 4.5 (standard) could not resolve
* Planning complex application architecture
* Working through intricate data transformations
* Handling edge cases in business logic
Switch to this when you need the AI to think harder about a problem.
A faster model that handles straightforward tasks efficiently. Use Sonnet 4.5 for:
* Simple UI changes (colors, layout, text)
* Adding straightforward CRUD features
* Quick code modifications
* Iterating rapidly on visual design
Sonnet 4.5 responds faster and uses fewer credits, making it ideal for rapid iteration cycles.
The fastest and most cost-effective model. Use Haiku 4.5 for:
* Minor text changes
* Simple styling updates
* Quick questions about your code (in Ask mode)
* Small, well-defined edits
Haiku 4.5 is best for tasks where speed matters more than depth.
An OpenAI model that offers a different approach. Use GPT-5.1 when:
* You want a second opinion on an approach
* Opus has difficulty with a specific task
* You prefer GPT-style outputs for certain tasks
Available in standard and high reasoning variants.
A Google model offering yet another approach. Use Gemini 3 Pro when:
* You want to try a different model's take on a problem
* Exploring alternatives for specific use cases
***
## Cost implications
More powerful models and higher reasoning levels consume more credits per message. As a general rule:
* **Haiku 4.5** uses the fewest credits per interaction
* **Sonnet 4.5** uses moderate credits
* **Opus 4.5** uses more credits but delivers the best results for complex tasks
* **High reasoning variants** use the most credits
A practical workflow: use Opus 4.5 for initial app creation and complex features, then switch to Sonnet 4.5 or Haiku 4.5 for quick refinements and small edits. This balances quality with cost.
***
## Model selection strategy
Here is a practical approach to model selection:
1. **Start with Opus 4.5** for building new features and complex logic
2. **Switch to Sonnet 4.5** when iterating on UI and making straightforward changes
3. **Use Haiku 4.5** for quick questions and minor edits
4. **Upgrade to Opus 4.5 - High** when stuck on a difficult bug or architectural decision
5. **Try GPT-5.1** if you want an alternative perspective on a problem
***
## What's next
* Learn how the editor works: [The Editor](/getting-started/interface)
* Understand the live preview: [Preview & Sandbox](/building-apps/preview-and-sandbox)
* Tips for communicating with the AI: [Prompting Tips](/tips/prompting)
# Creating an App
Source: https://docs.vybe.build/building-apps/creating-an-app
Three ways to start building — from scratch, from a recipe, or from a template
Every Vybe app is a full-stack Next.js 15 application with its own database, live preview, and deployment pipeline. You can create one in under a minute.
***
## Three ways to create an app
Start with a blank canvas and describe what you want the AI to build.
Pick a pre-configured starter with guided setup steps and built-in integrations.
Clone a full app blueprint created by another user or your team.
***
## Creating an app from scratch
This is the most common path. You describe what you need, and the AI builds it.
From your workspace, click the **New App** button. Enter a name for your app.
In the chat panel, write a prompt describing the app you want to build. Be specific about the data sources, features, and layout your team needs.
> Build a customer support dashboard that shows open tickets from our database, lets agents update ticket status, and displays resolution time metrics in a chart.
The AI scaffolds your entire application — creating pages, components, database tables, and API routes. You can watch the progress in real-time through the live preview.
The more specific your initial prompt, the better the result. Include details about data sources, user workflows, and the layout you want. You can always iterate after the first build.
***
## Creating an app from a recipe
Recipes are pre-configured app starters designed for common use cases. They come with specific integrations and guided setup steps.
Click **New App** and browse the recipe gallery. Recipes are organized by category and filterable by integration type.
Select a recipe that matches your use case — for example, "Jira Dashboard", "Stripe Chargeback Tracker", or "Salesforce Pipeline View". Each recipe shows which integrations it uses.
After creating the app, a sidebar appears with the recipe's setup steps. These steps walk you through connecting the required integrations, configuring data sources, and customizing the app for your needs.
As you work through each step, mark it as complete to track your progress.
Learn more about recipes in the [Recipes](/building-apps/recipes) guide.
***
## Creating an app from a template
Templates are full app blueprints published by other users. They give you a working app to customize.
Click **New App** and switch to the templates view. Browse available templates created by your team or the community.
Each template shows its name, description, and author. Click on a template to preview what it includes.
When you create an app from a template, you get a full, independent copy. Any changes you make do not affect the original template.
Learn more about templates in the [Templates](/building-apps/templates) guide.
***
## Naming your app
When you create an app, you give it a name. Vybe generates a URL-friendly slug from that name automatically.
* App names should be descriptive and concise (e.g., "Chargeback Tracker", "Sales Pipeline")
* The slug is used in your app's deployed URL: `appslug-orgslug.vybe.build`
* You can rename your app later from app settings, but the slug remains fixed after creation
The app slug cannot be changed after creation. Choose a name you are comfortable keeping as the permanent URL identifier.
***
## What happens when you create an app
When you click create, Vybe handles the full setup automatically:
1. **Sandbox environment** — A sandboxed development environment spins up for your app
2. **Project scaffolding** — The AI generates a standard Next.js 15 project with pre-installed libraries (Shadcn UI, Tailwind CSS, Recharts, and more)
3. **Database provisioning** — Your app gets its own PostgreSQL database, ready for the AI to create tables and run queries
4. **Dev server start** — The Next.js development server starts automatically, and the live preview becomes available
5. **Git repository** — A Git repository is initialized to track every change the AI makes
The entire process takes a few seconds. Once complete, you are in the editor with a live preview and an active chat session ready for your first prompt.
***
## App settings
After creating your app, you can configure additional settings from the sidebar:
| Setting | Description |
| ----------------------- | --------------------------------------------------------- |
| **Custom instructions** | Persistent context the AI reads before every interaction |
| **Integrations** | Connect services and databases your app needs |
| **Access level** | Control who in your organization can view or edit the app |
| **Workflows** | Enable background jobs and scheduled tasks |
***
## What's next
* Learn how to interact with the AI to build your app: [The AI Chat](/building-apps/ai-chat)
* Explore the editor interface: [The Editor](/getting-started/interface)
* Understand the live development environment: [Preview & Sandbox](/building-apps/preview-and-sandbox)
# Custom Instructions
Source: https://docs.vybe.build/building-apps/custom-instructions
Give the AI persistent context about your app — coding conventions, design guidelines, and domain rules
Custom instructions let you set persistent context that the AI reads before every interaction with your app. Instead of repeating the same guidance in every message, you write it once and the AI follows it automatically.
***
## What are custom instructions?
Custom instructions are a block of text you attach to your app that the AI includes in its context for every message. They act as standing orders — the AI reads them before processing each of your prompts and follows them throughout the conversation.
Use custom instructions for anything the AI should always know or always do when working on your app.
***
## Setting custom instructions
From the editor sidebar, open your app's settings.
The custom instructions text area is in the app settings panel.
Enter your instructions as plain text. Be clear and specific about what you want the AI to do or avoid.
Your instructions take effect immediately. The AI reads them before every subsequent message in any thread for this app.
***
## What to include
Custom instructions are most effective for persistent rules and context that apply across your entire app. Here are common use cases:
### Coding conventions
Tell the AI how you want code structured and formatted:
```
Always use TypeScript interfaces, never type aliases.
Use named exports, not default exports.
Keep components under 150 lines — split into smaller components if needed.
```
### Design guidelines
Establish visual standards for your app:
```
Use dark mode by default.
All buttons should use the "outline" variant unless they are primary actions.
Use the blue-600 color for all primary accent elements.
Tables should always have pagination with 25 rows per page.
```
### Domain-specific terminology
Define terms the AI should use consistently:
```
A "case" refers to a customer support ticket.
"Resolution time" is measured from case creation to first response, not final closure.
"Active users" means users who logged in within the last 30 days.
```
### Data handling rules
Set rules for how data should be queried and displayed:
```
Always sort tables by created date descending unless the user specifies otherwise.
Use metric units for all measurements.
Format dates as "Jan 15, 2025" — never use ISO format in the UI.
Currency values should always show two decimal places.
```
### Architecture patterns
Define patterns the AI should follow:
```
All API routes should validate input with Zod schemas.
Database queries should use pagination — never fetch unbounded result sets.
Use server components for data fetching. Only use client components when interactivity is required.
```
***
## Examples
Here are complete custom instruction sets for different types of apps:
```
This is an internal CRM dashboard for the sales team.
Terminology:
- "Deal" = a sales opportunity in our pipeline
- "Account" = a company we are selling to or have sold to
- "Contact" = an individual person at an account
Design rules:
- Use a sidebar layout with navigation on the left
- All tables should be sortable and searchable
- Show currency values in USD with two decimal places
- Use green for "Won", red for "Lost", blue for "In Progress"
Data rules:
- Default sort: most recently updated first
- Pagination: 50 rows per page for all tables
- Always show the total count above tables
```
```
This is an operations monitoring dashboard.
Always use dark mode.
Charts should use the following color palette: #3B82F6, #10B981, #F59E0B, #EF4444, #8B5CF6.
All timestamps should display in the user's local timezone.
Use 24-hour time format.
When building charts:
- Include a legend below the chart
- Use tooltips that show exact values on hover
- Default time range should be "Last 7 days"
```
```
This app manages customer support tickets.
Priority levels: Critical, High, Medium, Low
Status values: Open, In Progress, Waiting on Customer, Resolved, Closed
Always show ticket count badges next to status labels.
The default view should filter to "Open" and "In Progress" tickets only.
Sort by priority (Critical first), then by creation date (oldest first).
When displaying customer information, always show:
- Company name
- Contact name
- Account tier (Enterprise, Pro, Free)
```
***
## Tips for effective instructions
"Use dark mode" is better than "make it look nice." Specific instructions produce consistent results.
Focus on rules the AI should always follow. Do not include one-time instructions — put those in chat messages instead.
Group related instructions under headings (Design, Data, Terminology). This helps the AI parse and apply them correctly.
Refine your instructions as your app evolves. Remove rules that no longer apply and add new ones as patterns emerge.
***
## How custom instructions interact with prompts
Custom instructions are read by the AI alongside your chat messages. They do not override your prompts — instead, they provide background context. If your message conflicts with a custom instruction, the AI follows your message for that specific interaction.
For example, if your custom instructions say "use dark mode" but you send a message saying "make this page use light mode", the AI will apply light mode to that specific page.
Custom instructions apply to all threads within an app. You cannot set different instructions for different threads. If you need different AI behavior, create a separate app.
***
## What's next
* Learn how to create your first app: [Creating an App](/building-apps/creating-an-app)
* Improve your prompting technique: [Prompting Tips](/tips/prompting)
* Explore pre-configured starters: [Recipes](/building-apps/recipes)
# Preview & Sandbox
Source: https://docs.vybe.build/building-apps/preview-and-sandbox
How the live development environment works — real-time preview, hot reload, and sandbox lifecycle
Every Vybe app runs in its own sandboxed development environment. The sandbox gives your app an isolated runtime with a live preview that updates in real-time as the AI writes code.
***
## How the sandbox works
When you create an app or open an existing one, Vybe automatically provisions a sandbox environment. This sandbox is a fully isolated container that runs your Next.js development server with all the same capabilities as a local development setup.
The sandbox includes:
* A **Next.js 15 dev server** with hot module replacement
* A **PostgreSQL database** dedicated to your app
* Pre-installed **npm packages** (Shadcn UI, Tailwind CSS, Recharts, Lucide, and more)
* Access to your **connected integrations** and their credentials
***
## Live preview
The Preview tab in the editor shows your running app. As the AI creates or edits files, the preview updates automatically — you see changes appear within seconds.
### Real-time updates
The sandbox uses Next.js hot reload, so changes to your code are reflected in the preview almost instantly. You do not need to manually refresh — the preview updates on its own whenever:
* The AI creates a new file
* The AI modifies an existing file
* The AI installs a new package
* Database schema changes are applied
### Page navigation
If your app has multiple pages or routes, the **page selector** dropdown at the top of the preview lets you navigate between them. You can also navigate by clicking links within your app just as a regular user would.
### Interacting with your app
The preview is fully interactive. You can:
* Click buttons, fill out forms, and submit data
* Navigate between pages using your app's navigation
* Trigger API calls and see real-time results
* Test search, filtering, and pagination features
This lets you verify that your app works correctly as you build it.
***
## Handling preview errors
When your app encounters an error, the preview displays the error details instead of your app's UI.
### Error display
Runtime errors show:
* The error message
* A stack trace pointing to the file and line where the error occurred
* Context about what went wrong
### Sending errors to the AI
Click on an error in the preview to send it directly to the AI chat. The AI will:
1. Read the error message and stack trace
2. Examine the relevant source files
3. Diagnose the root cause
4. Fix the issue automatically
This is often the fastest way to resolve bugs — just click the error and let the AI handle it.
When you see an error in the preview, click it before trying to describe the problem manually. The error details give the AI precise information about what went wrong.
***
## Sandbox lifecycle
Understanding how sandboxes are managed helps you work efficiently with Vybe.
### Creation
A sandbox is created automatically when you:
* Create a new app
* Open an existing app that does not have an active sandbox
The sandbox starts within seconds and the dev server begins running immediately.
### Sleep and wake
To conserve resources, sandboxes may go to sleep after a period of inactivity. When this happens:
* Your code and database are fully preserved
* The sandbox restarts automatically when you return to the app
* Startup takes a few seconds as the dev server reinitializes
### Persistence
Everything in your sandbox persists between sessions:
* All source files and code changes
* Database tables and data
* Installed packages
* Environment variables and integration connections
You can close your browser and return later — your app will be exactly where you left it.
Sandbox sleep is automatic and does not affect your data or code. When you return to your app, the sandbox wakes up and your dev server restarts with all your files and data intact.
***
## Preview vs. deployment
The preview in your sandbox is a development build of your app. It differs from your deployed production app in a few ways:
| Aspect | Preview (Sandbox) | Deployed App |
| ----------------- | ----------------------------------------- | -------------------------------------- |
| **Build type** | Development mode with hot reload | Production build, optimized |
| **URL** | Internal sandbox URL | `appslug-orgslug.vybe.build` |
| **Performance** | Slower (dev mode overhead) | Faster (compiled and optimized) |
| **Error display** | Detailed error messages with stack traces | User-friendly error pages |
| **Access** | Only you (the builder) | Anyone with access to the deployed URL |
The preview sandbox is for development only. To share your app with your team, you need to deploy it. See [Deploying](/deployment/deploying) for details.
***
## What's next
* Learn about the code your app is built with: [Working with Code](/building-apps/working-with-code)
* Understand version history and rollback: [Version History](/building-apps/version-history)
* Deploy your app: [Deploying](/deployment/deploying)
# Recipes
Source: https://docs.vybe.build/building-apps/recipes
Pre-configured app starters with guided setup steps and built-in integrations
Recipes are curated app starters designed for common business use cases. Each recipe comes with pre-connected integrations, a guided setup flow, and example schemas that get you to a working app faster than building from scratch.
***
## What is a recipe?
A recipe is a pre-configured starting point for building an app. Unlike templates (which are full app copies), recipes provide:
* **Integration requirements** — A list of services the app needs (e.g., Stripe, Jira, Salesforce)
* **Guided setup steps** — A step-by-step walkthrough that appears in the editor sidebar
* **Pre-defined structure** — Database schemas, API patterns, and UI layouts tailored to the use case
* **Tags and categories** — Organized by use case for easy browsing
Recipes are maintained by the Vybe team and community. They represent proven patterns for building specific types of internal tools.
***
## Browsing recipes
Click **New App** from your workspace. The recipe gallery is displayed alongside the option to start from scratch.
Use the category filters to narrow down recipes by use case. You can also filter by integration type if you know which services you want to connect.
Each recipe card shows the name, description, required integrations, and tags. Click on a recipe to create your app with that starter configuration.
***
## Following recipe steps
After creating an app from a recipe, a sidebar panel appears in the editor with the recipe's setup steps. These steps guide you through configuring the app for your specific setup.
### Step-by-step guidance
Recipe steps typically include:
1. **Connect integrations** — Link the required services (e.g., "Connect your Stripe account")
2. **Configure data sources** — Set up which data the app should pull from your connected services
3. **Customize the app** — Adjust the UI, add filters, or modify the layout to match your workflow
4. **Test the app** — Verify that data is flowing correctly and the app works as expected
### Tracking progress
Each step has a checkbox you can mark as complete as you work through the setup. This helps you track where you are in the configuration process, especially for recipes with multiple integration requirements.
You do not need to follow recipe steps in exact order. If you already have an integration connected, you can skip that step. The steps are guidance, not requirements.
***
## Example recipes
Here are some common recipes available in the gallery:
| Recipe | Integrations | Description |
| ------------------------------ | ------------ | ------------------------------------------------------------- |
| **Jira Bug Tracker Dashboard** | Jira | View and manage open bugs, filter by priority and assignee |
| **Stripe Chargeback Manager** | Stripe | Track disputes, manage evidence submission, monitor win rates |
| **Salesforce Pipeline View** | Salesforce | Visualize your sales pipeline with filtering by stage and rep |
| **HubSpot Contact Explorer** | HubSpot | Search, filter, and manage contacts from your CRM |
| **Slack Channel Analytics** | Slack | Monitor message activity and engagement across channels |
The recipe gallery is regularly updated with new starters based on common use cases.
***
## Recipes vs. templates vs. from scratch
| Aspect | Recipe | Template | From Scratch |
| ------------------ | ------------------------------------------ | ------------------------------------ | --------------------------------- |
| **Starting point** | Guided setup with integration requirements | Full app copy you can modify | Blank canvas |
| **Setup guidance** | Step-by-step sidebar walkthrough | None — you start with a complete app | None — you describe what you want |
| **Integrations** | Pre-defined, connected during setup | Included from the source app | You choose as you build |
| **Best for** | Known use cases with specific integrations | Reusing a proven app design | Unique or custom requirements |
***
## Building on a recipe
Once you have completed the recipe steps, the app is yours to customize. You can:
* Ask the AI to add new features beyond what the recipe provides
* Modify the UI, add pages, or change the data model
* Connect additional integrations not included in the original recipe
* Use the app as a foundation and iterate from there
The recipe's guided steps remain available in the sidebar as a reference, even after you have completed them.
***
## What's next
* Learn about templates for reusable app blueprints: [Templates](/building-apps/templates)
* Customize AI behavior for your app: [Custom Instructions](/building-apps/custom-instructions)
* Connect additional integrations: [Integration Basics](/integrations/integration-basics)
# Templates
Source: https://docs.vybe.build/building-apps/templates
Start from pre-built app blueprints created by the Vybe team and community
Templates are full app blueprints you can clone and customize. They let you start from a proven app design instead of building from scratch.
***
## What is a template?
A template is a snapshot of a Vybe app that has been published for others to use. When you create an app from a template, you get a complete, independent copy with all the source code, components, and structure from the original.
Unlike recipes (which provide guided setup steps), templates give you a fully built app to customize. You skip the scaffolding phase and go straight to modifying and extending.
***
## Browsing templates
Click **New App** from your workspace and navigate to the templates view.
Templates are displayed as cards with a name, description, and author. Click on a template to see more details about what it includes. When you are ready, click to create your app from the template.
***
## Creating an app from a template
When you create an app from a template, Vybe:
1. Creates a new app in your workspace with a fresh name and slug
2. Copies all source files from the template into your app
3. Provisions a new database for your app (template data is not copied)
4. Starts the sandbox environment with the template code
Your new app is fully independent from the original template. Changes you make do not affect the template, and updates to the template do not affect your app.
Template copies include all source code and file structure, but not the original app's database data. You start with a clean database and can populate it using the AI or by connecting integrations.
***
## Customizing a template app
After creating an app from a template, you have full control. Common customization tasks include:
* **Connecting your integrations** — The template may reference services you need to connect to your own accounts
* **Updating the database schema** — Modify tables to match your specific data model
* **Changing the UI** — Adjust layouts, colors, and components to match your brand or preferences
* **Adding new features** — Use the AI chat to build additional pages and functionality beyond what the template provides
The AI has full context of the template's code, so you can reference existing patterns when asking for changes:
> Make the sidebar navigation collapsible, similar to how the main dashboard template handles it.
***
## Templates vs. recipes
| Aspect | Template | Recipe |
| ----------------- | ---------------------------------------- | ------------------------------------------------------- |
| **What you get** | A complete, working app you can clone | A guided setup flow with integration requirements |
| **Setup process** | Immediate — the app works out of the box | Step-by-step — you configure integrations and data |
| **Data included** | No — you start with a clean database | No — data comes from your connected integrations |
| **Best for** | Reusing a proven app design quickly | Building from a structured starting point with guidance |
***
## What's next
* Set persistent AI instructions for your app: [Custom Instructions](/building-apps/custom-instructions)
* Explore pre-configured starters: [Recipes](/building-apps/recipes)
* Connect your data sources: [Integration Basics](/integrations/integration-basics)
# Version History & Rollback
Source: https://docs.vybe.build/building-apps/version-history
Vybe automatically saves checkpoints as you build so you can restore your app to a previous state
Vybe automatically saves a checkpoint of your app's code every time the AI finishes making changes. If something goes wrong, you can restore to any previous checkpoint directly from the chat.
***
## How checkpoints work
Every time the AI modifies your app's files and finishes responding, Vybe saves a checkpoint — a snapshot of all your source files at that moment. You'll see a confirmation appear below the AI's message:
> Your progress has been saved.
Each checkpoint is tied to a specific AI response in your conversation. This gives you a restore point for every set of changes the AI makes.
You do not need to manually save your work. Checkpoints are created automatically whenever the AI modifies files.
***
## Restoring to a checkpoint
If the AI makes a change that breaks your app or produces an undesired result, you can restore to any previous checkpoint.
Scroll through the conversation to find the checkpoint you want to restore to — the last point where your app was in a good state. Each checkpoint appears directly below the AI message that created it.
Click the **Restore** button on the checkpoint. A confirmation dialog appears showing what will happen.
Review the confirmation and click to proceed. The restore:
* Reverts all source files to their state at that checkpoint
* **Deletes all chat messages** in the current thread that came after that checkpoint
Restoring to a checkpoint is irreversible. All chat messages after the selected checkpoint are permanently deleted from the current thread. Make sure you have selected the right checkpoint before confirming.
***
## What restore affects
**Restored:**
* All source files — code, components, pages, API routes, and configuration files are reverted to their state at the checkpoint
* File structure — files added after the checkpoint are removed; files deleted after the checkpoint are brought back
**Not restored:**
* **Database data** — if the AI created tables, ran migrations, or inserted data after the checkpoint, those changes remain in your database. You may need to ask the AI to adjust the database separately after restoring
* **Published deployments** — restoring does not affect your live deployed app. If you want the deployed version to reflect the restored code, you need to publish again after restoring
***
## Best practices
* **Restore early** — if you notice an issue, restore before the AI makes additional changes on top of the problem. This keeps your conversation clean and avoids compounding errors
* **Build in small steps** — making one change at a time means each checkpoint captures a focused set of changes, making it easier to identify exactly where something went wrong
* **Re-publish after restoring** — if your app is deployed and you restore to a previous checkpoint, remember to publish again so the live version matches your restored code
***
## What's next
* Learn about recipes for pre-configured starters: [Recipes](/building-apps/recipes)
* Customize AI behavior for your app: [Custom Instructions](/building-apps/custom-instructions)
* Deploy your app when it is ready: [Deploying](/deployment/deploying)
# Working with Code
Source: https://docs.vybe.build/building-apps/working-with-code
Understand the generated code structure, available libraries, and how to work with your Next.js app
Every Vybe app is a standard Next.js 15 application built on the App Router. The AI generates clean, idiomatic code using popular open-source libraries. Understanding the project structure and available tools helps you communicate more effectively with the AI.
***
## Project structure
Your app follows a standard Next.js 15 App Router layout:
```
/src
/app # Pages and API routes
/page.tsx # Homepage
/layout.tsx # Root layout
/api # API route handlers
/example/route.ts # Example API endpoint
/components # Reusable React components
/lib # Utility functions and helpers
/client-lib # Client-side libraries (auth, integrations)
/server-lib # Server-side libraries (database, external APIs)
/prisma
/schema.prisma # Database schema definition
/public # Static assets
```
* **`/src/app`** — Contains your pages (as `page.tsx` files) and API routes (as `route.ts` files). Each folder represents a URL path.
* **`/src/components`** — Reusable React components shared across pages.
* **`/src/lib`** — Shared utility functions, constants, and type definitions.
* **`/src/client-lib`** — Client-side libraries for authentication, integrations, and data queries. These are managed by Vybe and cannot be edited.
* **`/src/server-lib`** — Server-side libraries for database access, external APIs, and integration clients. Also managed by Vybe.
* **`/prisma/schema.prisma`** — Your database schema. The AI modifies this when creating or updating tables.
***
## Pre-installed libraries
Every Vybe app comes with a curated set of libraries pre-installed and ready to use.
### Shadcn UI
A collection of 50+ accessible, customizable UI components built on Radix primitives and Tailwind CSS. The AI uses these components by default when building interfaces.
Common components include:
| Component | Use Case |
| --------- | ---------------------------------- |
| `Button` | Actions, form submissions |
| `Table` | Data display with rows and columns |
| `Dialog` | Modal dialogs and confirmations |
| `Form` | Form layouts with validation |
| `Select` | Dropdown selection |
| `Card` | Content containers |
| `Tabs` | Tabbed navigation |
| `Badge` | Status indicators |
| `Input` | Text input fields |
| `Toast` | Notification messages |
### Recharts
A composable charting library for building data visualizations. The AI uses Recharts with Shadcn's chart wrapper components to create bar charts, line charts, pie charts, area charts, and more.
### Tailwind CSS
Utility-first CSS framework for styling. All Vybe apps use Tailwind for layout, spacing, colors, typography, and responsive design. The AI writes Tailwind classes directly in your JSX.
### Lucide
An icon library with hundreds of icons. The AI uses Lucide icons throughout your app for buttons, navigation, status indicators, and decorative elements.
### Sonner
A toast notification library. The AI uses Sonner to display success messages, error alerts, and other transient notifications to your app's users.
***
## Server components vs. client components
Next.js 15 uses React Server Components by default. This affects how the AI writes your code:
* **Server Components** (default) — Rendered on the server. Can directly access databases and server-side APIs. Cannot use browser APIs, event handlers, or React hooks like `useState`.
* **Client Components** — Rendered in the browser. Required for interactivity (forms, buttons, state management). Must include the `"use client"` directive at the top of the file.
```typescript theme={null}
// Server Component (default) — no directive needed
export default async function DashboardPage() {
const data = await fetchFromDatabase();
return ;
}
```
```typescript theme={null}
// Client Component — requires "use client" directive
"use client";
import { useState } from "react";
export default function SearchForm() {
const [query, setQuery] = useState("");
return setQuery(e.target.value)} />;
}
```
The AI handles this distinction automatically, but knowing it helps you understand why some components have the `"use client"` directive and others do not.
***
## Dynamic routes
Next.js 15 uses Promise-based params for dynamic routes. If your app has routes like `/customers/[id]`, the AI generates code that awaits the params:
```typescript theme={null}
export default async function CustomerPage({
params,
}: {
params: Promise<{ id: string }>;
}) {
const { id } = await params;
// Fetch customer by id...
}
```
This is a Next.js 15 convention that differs from earlier versions. The AI handles it correctly by default.
***
## Locked files
Certain system files in your project are locked and cannot be modified by the AI or manually. These files are managed by Vybe to ensure your app's infrastructure remains stable.
Locked files include:
* `package.json` and `package-lock.json` — Dependency management
* `next.config.js` — Next.js configuration
* `tsconfig.json` — TypeScript configuration
* `prisma/schema.prisma` — Database schema (managed via AI SQL tools)
* `.env` — Environment variables (managed through app settings)
* Client and server library files in `src/client-lib` and `src/server-lib`
The AI is aware of locked files and will not attempt to edit them directly. For example, instead of editing `package.json`, the AI uses a dedicated tool to install packages. Instead of editing `prisma/schema.prisma` directly, the AI runs SQL migrations.
***
## Viewing code in the editor
The Code tab in the editor lets you browse your app's source code:
* **File explorer** — A tree view of your project's files and folders in the left sidebar
* **Syntax highlighting** — Full highlighting for TypeScript, JSX, CSS, JSON, SQL, and more
* **File search** — Find specific files by name
* **Diff view** — After the AI makes changes, see exactly what was added, removed, or modified
The Code tab is read-only. All code changes go through the AI chat.
***
## Working with the AI on code
When asking the AI to modify code, you can reference specific files, components, or patterns:
> Change the table on the customers page to show 50 rows per page instead of 25.
> Move the sidebar navigation into its own component so I can reuse it on other pages.
> Add form validation to the create customer page — name and email should be required.
The AI understands your project structure and can find the relevant files based on your description. You do not need to specify exact file paths unless you want to be precise.
***
## What's next
* Understand version history and rollback: [Version History](/building-apps/version-history)
* Learn about the live preview: [Preview & Sandbox](/building-apps/preview-and-sandbox)
* Manage your app's data: [App Data](/data/app-data)
# Internal Database
Source: https://docs.vybe.build/data/app-data
Every Vybe app includes a dedicated PostgreSQL database that the AI creates and manages for you
Every Vybe app comes with its own PostgreSQL database powered by [Neon](https://neon.tech). You do not need to provision, configure, or manage it — the AI handles everything from creating tables to writing queries based on your descriptions.
***
## How it works
When you describe what your app needs, the AI automatically creates the database schema to support it. For example:
> Create a table for tracking customer support tickets with status, priority, assignee, and timestamps.
The AI will:
1. Create a `tickets` table with the appropriate columns and data types
2. Add indexes for commonly queried fields
3. Set up any necessary relationships to other tables
4. Generate the API routes and UI components to work with the data
As your app evolves, the AI manages schema changes for you. If you ask to add a new column or create a relationship between tables, the AI modifies the schema and updates the relevant code automatically.
You can ask the AI to seed your database with sample data for testing. Try a prompt like: "Add 20 sample support tickets with realistic data."
***
## Schema visualization
The **Data** tab in the app editor includes an interactive ERD (Entity Relationship Diagram) that shows your complete database schema at a glance.
The diagram displays:
* All tables and their columns
* Data types for each column
* Primary keys and foreign key relationships
* Relationship lines connecting related tables
The ERD updates automatically whenever the AI modifies your schema, so it always reflects the current state of your database.
***
## Table browser
The Data tab also includes a table browser where you can work with your data directly.
From the table browser, you can:
* **View rows** in any table with sortable columns
* **Add rows** by filling in a form for each column
* **Edit rows** by clicking on a cell and modifying its value
* **Delete rows** individually or in bulk
This is useful for inspecting data while building, verifying that the AI created the right schema, or manually adjusting records without writing SQL.
***
## How the AI accesses the database
The AI generates server-side code that queries your database using raw SQL with parameterized queries. All queries run in Next.js API routes or server components — never in client-side code.
```typescript theme={null}
import { sql } from '@/lib/db';
export async function GET() {
const tickets = await sql`
SELECT * FROM tickets
WHERE status = 'open'
ORDER BY created_at DESC
`;
return Response.json(tickets);
}
```
All database queries run server-side. The AI places them in Next.js API routes (`app/api/...`) or server components to keep your database credentials secure.
***
## Working with your database through chat
You can ask the AI to perform database operations directly from the chat:
> Show me all tickets created in the last 7 days.
> Add a "priority" column to the tickets table with values: low, medium, high, critical.
> Delete all test records from the users table where the email contains "example.com".
The AI executes these operations and shows you the results inline. For destructive operations like deleting data or dropping tables, the AI will confirm before proceeding.
***
## Best practices
* **Let the AI manage the schema.** Describe what you need in plain language and let the AI create the tables, columns, and relationships. You can always refine with follow-up prompts.
* **Use the Data tab to verify.** After the AI creates or modifies your schema, check the ERD and table browser to confirm everything looks right.
* **Seed data for testing.** Ask the AI to generate realistic sample data so you can test your app's UI and workflows before connecting real data.
* **Be specific about data types.** If you need a column to be an enum, a timestamp, or a JSON field, mention it in your prompt. The AI will choose sensible defaults, but explicit instructions lead to better results.
# Data Queries
Source: https://docs.vybe.build/data/data-queries
Save reusable named queries and share them across your Vybe apps
Data queries are reusable, named queries that you save once and reference across multiple apps. Instead of writing the same complex query in every app that needs it, you create a data query and use it by name.
***
## Why use data queries
Data queries solve a common problem: you have a complex query that multiple apps need, and you do not want to duplicate it everywhere.
For example, your team might need a query that calculates monthly recurring revenue from your billing database. Rather than writing and maintaining that query in each app separately, you save it as a data query called "Monthly MRR" and reference it anywhere.
Benefits of data queries:
* **Reusable** — Write once, use in any app across your organization
* **Consistent** — Every app uses the same query logic, so results are always consistent
* **Maintainable** — Update the query in one place and all apps pick up the change
* **Shareable** — Any team member in your organization can use saved queries
***
## Query types
Data queries support two types of data sources:
| Type | Data source | Use case |
| --------------- | ---------------------------------------------------------- | ------------------------------------ |
| **SQL queries** | Connected external databases (PostgreSQL, MySQL, Redshift) | Query your existing database tables |
| **API queries** | Connected integration services | Fetch data from third-party services |
***
## Creating a data query
Navigate to **Integrations** in the left sidebar and scroll to the **Data Queries** section.
Click **Create Data Query** to start building a new query.
Choose which connected database or integration service the query should run against. Only databases and integrations that are already connected to your organization appear here.
Give your query a unique name and write the query itself. For SQL queries, write standard SQL for your database type. For API queries, configure the request parameters.
Query names must be unique within your organization. Use descriptive names that make the query's purpose clear:
* `monthly-mrr` instead of `query1`
* `active-users-last-30-days` instead of `users`
* `open-support-tickets` instead of `tickets`
Click **Save**. The query is now available organization-wide.
***
## Using data queries
Once saved, data queries can be used in several ways:
### In the AI chat
The AI can execute your saved data queries during a conversation. Reference the query by name:
> Run the "monthly-mrr" data query and show me the results.
> What does the "active-users-last-30-days" query return right now?
The AI identifies the saved query, executes it against the configured data source, and displays the results inline.
### In app code
The AI can generate code that references your saved data queries when building app features. When you describe what your app needs, the AI may use an existing data query rather than writing a new query from scratch.
### Across multiple apps
Because data queries are organization-scoped, any app in your workspace can use them. This is particularly useful when multiple apps need the same data — for example, a dashboard app and a reporting app that both need the same revenue metrics.
***
## Managing data queries
From the **Data Queries** section on the Integrations page, you can:
* **Edit** — Update the query logic or rename it. Changes apply everywhere the query is used.
* **Test** — Run the query and preview the results before using it in an app.
* **Delete** — Remove a query you no longer need. Apps that reference a deleted query will need to be updated.
Deleting a data query does not automatically update apps that reference it. If you delete a query that apps depend on, those apps will encounter errors until you update them.
***
## Best practices
* **Use descriptive names.** Query names should make their purpose obvious without needing to read the SQL.
* **Start with the AI chat.** Test a query in the chat first, then save it as a data query once you are happy with the results.
* **Keep queries focused.** A single data query should answer one question. If you find yourself writing a query that does too many things, split it into multiple queries.
* **Document complex queries.** For queries with non-obvious logic (joins across many tables, calculated fields), add a clear name and consider mentioning the purpose when you create it so other team members understand what it does.
# External Databases
Source: https://docs.vybe.build/data/external-data
Connect your existing PostgreSQL, MySQL, and Amazon Redshift databases to use their data in Vybe apps
You can connect your existing databases to Vybe and use their data across your apps. This lets you build internal tools on top of production data without moving or duplicating it.
***
## Supported databases
| Database | Authentication | SSH Tunnel | Read-only Mode |
| ------------------- | ------------------------------------------- | ---------- | -------------- |
| **PostgreSQL** | Connection string or individual credentials | Yes | Yes |
| **MySQL** | Connection string or individual credentials | Yes | Yes |
| **Amazon Redshift** | AWS IAM role assumption | No | No |
***
## Connecting a database
Navigate to **Integrations** in the left sidebar and scroll to the **Databases** section.
Click **Connect Database** and choose **PostgreSQL**, **MySQL**, or **Amazon Redshift**.
For PostgreSQL and MySQL, provide either a connection string or individual credentials (host, port, database name, username, password). For Amazon Redshift, provide your cluster details and IAM role ARN. Redshift uses AWS IAM role assumption for secure, credential-free access.
Optionally enable **read-only mode** to prevent accidental writes, or **SSH tunnel** to route the connection through an SSH tunnel for databases behind a firewall.
Vybe validates the connection before saving. If the connection fails, check your credentials, firewall rules, and SSH configuration.
Enable read-only mode for production databases to prevent accidental data modification. All workspace members can query connected databases, so read-only mode provides an important safety net.
***
## Read-only mode
When read-only mode is enabled, Vybe enforces read-only transactions on every query to the database. This means:
* `SELECT` queries work normally
* `INSERT`, `UPDATE`, `DELETE`, and DDL statements are blocked
* The AI cannot modify your data, even if you ask it to
This is the recommended setting for production databases. You get full read access for dashboards, reports, and data exploration without any risk of accidental writes.
***
## SSH tunnel connections
For databases behind a firewall or in a private network, Vybe supports SSH tunnel connections.
On the **Integrations** page, scroll to the **SSH Keys** section and click **Create SSH Key**. Vybe generates a public/private key pair.
Copy the public key and add it to the `~/.ssh/authorized_keys` file on your SSH bastion host or jump server.
When connecting a database, enable the **SSH tunnel** option and provide the SSH host, port, username, and the SSH key you created.
Vybe connects to your SSH server first, then tunnels the database connection through it. The test step verifies both the SSH connection and the database connection.
SSH keys can be reused across multiple database connections. Create one key for your bastion host and use it for all databases accessible from that server.
***
## Organization-wide access
Connected databases are available to all members of your organization. Once you connect a database, any team member can:
* Query it from the AI chat in any app
* Use it as a data source when building apps
* Reference it in saved data queries
There is no per-app database configuration — connected databases are shared at the organization level.
***
## Using external databases
Once connected, you can interact with external databases in two ways:
### Through the AI chat
Ask the AI to query your external database directly during a conversation:
> Show me the top 10 customers by revenue from our analytics database.
> How many orders were placed last month in the production database?
The AI identifies which connected database to query, writes the SQL, executes it, and displays the results inline.
### From app code
The AI generates server-side code that queries your external databases using Vybe's helper functions. Each database type has its own helper with parameterized query support.
```typescript theme={null}
import { queryExternalDatabasePostgres } from '@/server-lib/external-db-postgres';
const customers = await queryExternalDatabasePostgres(
'My Analytics DB',
'SELECT name, revenue FROM customers ORDER BY revenue DESC LIMIT 10',
[]
);
```
***
## Redshift specifics
Amazon Redshift connections work differently from PostgreSQL and MySQL:
* **Authentication**: Uses AWS IAM role assumption instead of username/password credentials. You provide the IAM role ARN that Vybe assumes to access your cluster.
* **No SSH tunnel**: Redshift connections do not support SSH tunneling. Ensure your Redshift cluster is accessible from Vybe's IP range.
* **Asynchronous queries**: Redshift queries are executed asynchronously. The helper function returns a result object with a status field that you should check before accessing the data.
```typescript theme={null}
const result = await queryExternalDatabaseRedshift(
'My Redshift Cluster',
'SELECT * FROM sales WHERE region = :region',
{ region: 'us-east' }
);
if (result.status === 'FINISHED') {
// Access result.records
}
```
***
## Troubleshooting
Check that your database is accessible from external networks. If it is behind a firewall, use an SSH tunnel connection. Verify that the host, port, and credentials are correct.
Confirm that the public key is added to your server's `authorized_keys` file. Verify the SSH host, port, and username. Ensure the SSH server allows tunneling (check `AllowTcpForwarding` in your SSH config).
Your database user may not have access to the tables you are querying. Check the user's permissions and grant `SELECT` access to the relevant schemas and tables.
# Database Overview
Source: https://docs.vybe.build/data/overview
Understand how Vybe handles data — from built-in databases to external connections and reusable queries
Every Vybe app comes with its own PostgreSQL database, and you can connect external databases from your existing infrastructure. The AI manages your schema, writes queries, and builds data-driven interfaces — all from your descriptions.
***
## How data works in Vybe
When you create a new app, Vybe automatically provisions a dedicated PostgreSQL database powered by [Neon](https://neon.tech). As you describe what your app should do, the AI creates tables, defines relationships, and writes the queries your app needs.
You never need to write SQL or manage migrations manually. The AI handles it all based on your prompts:
> Create a project tracker with tasks, assignees, due dates, and status columns. Each task should belong to a project, and projects should have a team lead.
The AI will create the `projects` and `tasks` tables, set up foreign keys, and build the UI to display and edit the data.
***
## The Data tab
The **Data** tab in the app editor gives you a visual interface for exploring and managing your app's database. It includes:
| Feature | Description |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| **Schema diagram** | An interactive ERD (Entity Relationship Diagram) showing all tables, columns, and relationships |
| **Table browser** | View rows in any table, with sorting and filtering |
| **Inline editing** | Add, edit, and delete rows directly from the browser |
The Data tab reflects the current state of your database in real time. Any changes the AI makes — creating a table, adding a column, inserting seed data — appear immediately.
***
## Database categories
Vybe supports two categories of databases:
Your app's built-in PostgreSQL database. The AI creates and manages it automatically as you build. Every app gets one.
Your existing databases (PostgreSQL, MySQL, Amazon Redshift) connected to Vybe. Query production data without moving it.
***
## Data queries
Beyond the built-in and external databases, Vybe lets you create **data queries** — reusable, named queries that you save once and reference across multiple apps.
Data queries can run against:
* Connected external databases (SQL queries)
* Connected integration services (API queries)
Saved queries are scoped to your organization, so any team member can use them. This is especially useful for complex queries that multiple apps need.
[Learn more about Data Queries](/data/data-queries)
***
## What's next
Learn how the AI creates and manages your app's built-in database.
Connect your existing PostgreSQL, MySQL, or Redshift databases.
Save and reuse queries across your apps.
# App Analytics
Source: https://docs.vybe.build/deployment/analytics
Track how your team uses your deployed app with built-in analytics
Once your app is deployed, the **Analytics** tab in the editor gives you visibility into how your team is using it. Track page visits, identify popular features, and use the data to guide what you build next.
***
## Accessing analytics
Analytics are available in the editor for any deployed app:
1. Open your app in the editor
2. Click the **Analytics** tab
If your app has not been deployed yet, the Analytics tab will not show data. Deploy your app first to begin collecting usage information.
***
## What is tracked
The Analytics tab tracks page visits across your deployed app:
| Metric | Description |
| ------------------ | ------------------------------------------------------------- |
| **Page path** | Which pages users visit (e.g., `/`, `/customers`, `/reports`) |
| **Visit count** | How many times each page has been visited |
| **Usage patterns** | Which pages are visited most frequently |
Analytics are collected for all users who access your deployed app, giving you a complete picture of how the tool is being used across your team.
***
## Using analytics data
Analytics help you make informed decisions about your app:
* **Identify popular pages** — See which features your team uses most and make sure they are reliable and polished
* **Find unused pages** — If certain pages get little traffic, consider whether they are still needed or if they need better discoverability
* **Prioritize improvements** — Focus your time on the pages and features that have the most impact on your team
* **Validate new features** — After adding a new page or feature, check analytics to see if your team is adopting it
If a page you expected to be popular is not getting traffic, ask the AI to improve its navigation placement or add a link from the dashboard.
***
## Scope
Analytics are scoped to a single app. Each app has its own independent analytics data showing usage for that specific tool.
If you have multiple apps deployed, you view analytics for each one separately from within that app's editor.
***
## What is next
* Learn how deployment works: [Deploying Your App](/deployment/deploying)
* Understand how your app URL is structured: [App URLs & Routing](/deployment/urls-and-routing)
* Control who can access your app: [App Access](/teams/app-access)
# Deploying Your App
Source: https://docs.vybe.build/deployment/deploying
Build and publish your app to a production URL with one click
When your app is ready for your team, click **Publish** to publish it to a production URL. Vybe handles the entire build and deployment process — you do not need to configure hosting, CI/CD pipelines, or infrastructure.
***
## How to deploy
Navigate to the app you want to deploy. Make sure you have tested it in the preview and are satisfied with the current state.
Click the **Publish** button in the editor toolbar. Vybe begins building your app immediately.
After clicking Publish, you'll see a **Publishing** indicator while Vybe builds and deploys your app.
Your app is now live at its production URL:
```
https://-.vybe.build
```
Share this URL with your team. Only authenticated members of your organization with access to the app can view it.
Make sure your app builds successfully in the preview before deploying. You can ask the AI to run type checks to catch errors early.
***
## What happens during deployment
When you click Deploy, Vybe runs through several steps behind the scenes:
1. **Build** — Your Next.js app is compiled and optimized for production
2. **Environment injection** — Database URLs, API keys, integration credentials, and server secrets are securely injected as environment variables
3. **Deploy** — The built app is deployed to Vercel's infrastructure with HTTPS and automatic scaling
4. **Register** — Your production URL is activated and ready to serve traffic
The first time you deploy an app, Vybe creates a new Vercel project for it. Subsequent deployments update the existing project with your latest changes.
***
## Handling deployment errors
If a deployment fails, Vybe displays the error details:
* **Error message** — A description of what went wrong
* **Failed step** — Which stage of the pipeline failed (build, deploy, etc.)
Common causes of deployment errors include:
* TypeScript compilation errors in your code
* Missing or misconfigured dependencies
* Invalid environment variable references
Review the error details, fix the issue in the editor (or ask the AI to help), and deploy again.
***
## Redeploying
After making changes to your app, click **Deploy** again to publish the updated version. Each deployment creates a new version of your app, replacing the previous one at the same production URL.
There is no limit to how many times you can deploy. You can iterate quickly — make a change, deploy, test with your team, and repeat.
***
## Deployment history
Vybe tracks your deployment history so you can see when each version was published and whether it succeeded or failed. This gives you a timeline of changes to your production app and helps you trace issues back to specific deployments.
***
## What is next
* Learn how your app URL is structured and how routing works: [App URLs & Routing](/deployment/urls-and-routing)
* View usage data for your deployed app: [App Analytics](/deployment/analytics)
# App URLs & Routing
Source: https://docs.vybe.build/deployment/urls-and-routing
Understand how your app URL is structured and how multi-page routing works
Every deployed Vybe app gets a production URL based on your app name and organization. Your app can have multiple pages, API routes, and dynamic segments — all powered by the Next.js App Router.
***
## Production URL
Your app is available at:
```
https://-.vybe.build
```
| Component | Source | Example |
| ------------ | ------------------------------ | ------------------------------------------- |
| **App slug** | Derived from your app name | "Sales Dashboard" becomes `sales-dashboard` |
| **Org slug** | Your organization's identifier | "Acme Corp" becomes `acme-corp` |
For example, an app called "Sales Dashboard" in the "Acme Corp" organization is deployed to:
```
https://sales-dashboard-acme-corp.vybe.build
```
***
## Multi-page routing
Your Vybe app can have as many pages as you need. The AI creates new pages using the Next.js App Router file convention, where each folder under `src/app` maps to a URL path.
| File path | URL |
| ---------------------------------- | ------------------ |
| `src/app/page.tsx` | `/` |
| `src/app/customers/page.tsx` | `/customers` |
| `src/app/settings/page.tsx` | `/settings` |
| `src/app/reports/monthly/page.tsx` | `/reports/monthly` |
When you ask the AI to add a new page, it creates the file in the correct location and adds navigation links so your users can find it.
> "Add a customers page with a searchable table showing all customers from our database."
***
## API routes
Your app can include server-side API routes that handle data fetching, form submissions, and other backend logic. API routes follow the same file-based routing pattern:
| File path | URL | Method |
| -------------------------------- | ---------------- | --------------- |
| `src/app/api/data/route.ts` | `/api/data` | GET, POST, etc. |
| `src/app/api/customers/route.ts` | `/api/customers` | GET, POST, etc. |
| `src/app/api/export/route.ts` | `/api/export` | GET, POST, etc. |
API routes run on the server and have access to your database, integrations, and environment variables.
***
## Dynamic routes
For pages that display a specific record — like a customer detail page or an order view — your app can use dynamic route segments:
| File path | URL pattern | Example URL |
| ----------------------------------- | ------------------ | ----------------- |
| `src/app/customers/[id]/page.tsx` | `/customers/:id` | `/customers/42` |
| `src/app/orders/[orderId]/page.tsx` | `/orders/:orderId` | `/orders/abc-123` |
Dynamic routes let you build detail views, edit forms, and record-specific pages without creating a separate file for each record.
> "Add a customer detail page that shows the full profile when I click on a customer in the table."
***
## Navigation
When the AI creates new pages, it also wires up navigation so your users can move between them. Depending on your app's layout, this may include:
* A sidebar with links to each page
* A top navigation bar
* Breadcrumbs for nested pages
* In-page links and buttons
You can ask the AI to change the navigation style at any time.
> "Switch the sidebar navigation to a top nav bar with dropdown menus."
***
## Authentication and access control
All routes in your deployed app — pages and API routes — are protected by Vybe authentication. Only members of your organization who have been granted access to the app can view it.
There is no public access by default. When someone visits your app URL without being authenticated, they are redirected to log in. This applies to every route in your app, including API endpoints.
If you need to share your app with someone outside your organization, you will need to invite them as a member first. See [App Access](/teams/app-access) for details on managing who can access your app.
***
## What is next
* Understand how deployment works end to end: [Deploying Your App](/deployment/deploying)
# Core Concepts
Source: https://docs.vybe.build/getting-started/core-concepts
Understand the key building blocks of Vybe and how they fit together
Before you start building, it helps to understand how Vybe is organized. This page covers the key concepts you will encounter throughout the platform.
***
## Organization
An organization is your team's workspace in Vybe. Everything you build — apps, integrations, connections, and members — belongs to an organization.
Each organization has:
* Its own set of apps and integrations
* A member list with role-based permissions (Owner, Admin, Editor, Member)
* Billing settings and credit balance
* A unique slug used in deployment URLs
You can belong to multiple organizations and switch between them from the sidebar. When you sign up, Vybe creates a personal organization for you automatically.
***
## App
An app is a full-stack Next.js 15 web application. Each app is a complete project with its own:
* **Codebase** — Pages, components, API routes, and server-side logic
* **Database** — A dedicated PostgreSQL instance with its own tables and data
* **Integrations** — Connections to external services configured for this app
* **Deployment** — A production URL where your team can access the app
You create apps by describing what you need in a chat with the AI agent. The agent generates the entire application — frontend, backend, database schema, and integration wiring — based on your description.
Each app is independent. Changes to one app never affect another. You can safely experiment without worrying about breaking other tools your team relies on.
***
## Thread
A thread is a conversation with the AI agent about a specific app. When you open an app in Vybe, you interact with it through threads.
Each app can have multiple threads. This is useful when you want to:
* Work on different features in parallel
* Keep a clean conversation history for a specific task
* Start fresh without losing previous context
Threads maintain full context about what you have discussed and changed. The AI agent remembers previous messages, code changes, and database modifications within a thread.
***
## AI Agent
The AI agent is the core of Vybe. It is the assistant that builds and modifies your apps based on your instructions. The agent can:
* Create and edit files (pages, components, API routes, styles)
* Run database queries (create tables, insert data, run migrations)
* Install packages from the approved list
* Connect and configure integrations
* Debug errors and fix issues
* Explain how your app works
The agent operates in two modes:
| Mode | Description | Use when |
| --------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
| **Agent** | Can read and modify your app's code, database, and integrations | You want to build or change something |
| **Ask** | Read-only access. Can answer questions but cannot make changes | You want to understand something without modifying the app |
You can switch between modes at any time from the chat input.
The AI agent works within the context of a single app. It has full access to that app's code, database, and connected integrations, but cannot access other apps in your organization.
***
## Sandbox
The sandbox is a live development environment where your app runs while you are building it. When the AI agent creates or modifies files, the sandbox compiles and runs the updated code automatically.
You can see your app running in real time through the **Preview** tab. Every change the agent makes — a new page, a styling update, a database query — is reflected in the preview within seconds.
The sandbox provides a full Node.js runtime with access to your app's database and connected integrations. It behaves exactly like your deployed app, so what you see in preview is what your users will see in production.
***
## Deployment
Deployment is the process of publishing your app so your team can use it. When you deploy, Vybe builds your app and makes it available at a production URL.
Deployed apps are accessible at:
```
https://-.vybe.build
```
For example, an app called "chargeback-tracker" in the "acme" organization would be deployed to `chargeback-tracker-acme.vybe.build`.
Key points about deployment:
* Only authenticated members of your organization can access deployed apps
* Each deployment creates a new version — you can roll back if needed
* Apps run on managed infrastructure with HTTPS and automatic scaling
* Environment variables and secrets are securely injected at deploy time
***
## Integration
An integration is a connection to an external service. Once you connect an integration at the organization level, it becomes available across all apps in your workspace.
Vybe supports several types of integrations:
| Type | Examples |
| --------------- | ---------------------------------------------------------- |
| **Services** | Slack, Salesforce, Jira, Stripe, HubSpot, Google Workspace |
| **Databases** | PostgreSQL, MySQL, Amazon Redshift |
| **Custom APIs** | Any REST service with key or token authentication |
| **Built-in** | People Data Labs, CrustData, OpenAI (no setup required) |
Integrations are connected once and shared across your organization. When you describe an app that needs Stripe data, the AI agent automatically uses your existing Stripe connection.
***
## Recipe
A recipe is a pre-configured app starter that combines a specific use case with guided setup steps. Recipes include:
* A description of the app being built
* Required integrations (the recipe prompts you to connect them before starting)
* A tailored prompt that generates a well-structured app
Recipes are useful when you want a head start on common use cases like building a CRM dashboard, a support ticket tracker, or a sales pipeline view.
***
## Template
A template is a reusable app blueprint created from an existing app. When you save an app as a template, it captures the full codebase and database schema so you or your team can spin up copies.
Templates are useful when you want to:
* Create a standardized starting point for similar apps
* Share a proven app structure across your organization
* Let team members customize a base app for their specific needs
***
## Credit
Credits are the unit of billing in Vybe. Each AI interaction — sending a message, generating code, running a query — consumes credits. The number of credits consumed depends on the AI model you use:
* More powerful models (like Claude Opus 4.5) cost more credits per interaction
* Lighter models (like Claude Haiku 4.5) cost fewer credits
* Non-AI actions like editing code manually or deploying do not consume credits
Your credit balance and usage are visible in your workspace settings. See [Plans & Credits](/getting-started/plans-and-credits) for details on plans and pricing.
***
## How it all fits together
Here is how the core concepts relate to each other:
```
Organization
├── Members (Owner, Admin, Editor, Member)
├── Integrations (Slack, Stripe, databases, APIs...)
├── Billing & Credits
│
└── Apps
├── App: Chargeback Tracker
│ ├── Threads (conversations with the AI agent)
│ ├── Codebase (pages, components, API routes)
│ ├── Database (PostgreSQL tables and data)
│ ├── Connected Integrations (Stripe, Slack)
│ └── Deployment → chargeback-tracker-acme.vybe.build
│
└── App: Sales Dashboard
├── Threads
├── Codebase
├── Database
├── Connected Integrations (Salesforce, HubSpot)
└── Deployment → sales-dashboard-acme.vybe.build
```
Your **organization** is the top-level container. It holds your **members**, **integrations**, and **apps**. Each **app** has its own **threads**, **codebase**, **database**, and **deployment**. The **AI agent** works within threads to build and modify apps, using your connected integrations as data sources.
# FAQ
Source: https://docs.vybe.build/getting-started/faq
Answers to common questions about building with Vybe
Find answers to the most common questions about Vybe. If your question is not covered here, reach out to the team at [team@vybe.build](mailto:team@vybe.build).
***
## General
Vybe is designed for internal tools — applications used by your team, not by external customers. Common examples include:
* **Dashboards** for tracking KPIs, revenue, or operational metrics
* **Admin panels** for managing users, orders, content, or any business entity
* **CRM interfaces** that pull data from Salesforce, HubSpot, or custom databases
* **Data explorers** for querying and visualizing data across multiple sources
* **Reporting tools** with charts, tables, and scheduled data refreshes
* **Workflow automation** like approval flows, triage queues, and task management
All apps are for authenticated organization members only. You cannot build public-facing applications with Vybe.
No. Vybe apps are designed for internal organizational use only. Every user who accesses a deployed Vybe app must be an authenticated member of your organization. There is no way to make an app publicly accessible.
If you need a public-facing application, Vybe is not the right tool. It is purpose-built for internal tools and business operations.
Vybe uses AI to generate full-stack applications from natural language, rather than requiring you to drag and drop components or write configuration files. Your apps are real Next.js 15 projects with full source code — not low-code abstractions.
Key differences:
* **AI-first** — You describe what you need and the AI writes the code
* **Full source code** — Every app is a standard Next.js project you can inspect and understand
* **Real databases** — Each app gets its own PostgreSQL database, not a spreadsheet backend
* **3,000+ integrations** — Connect to virtually any service your team uses
* **Production deployment** — Apps run on managed infrastructure with HTTPS and authentication
***
## AI & Models
Vybe supports multiple AI models that you can switch between at any time:
| Model | Strengths |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Claude Opus 4.5** | Most capable. Best for complex app generation, multi-step reasoning, and large refactors. This is the default model. |
| **Claude Sonnet 4.5** | Good balance of quality and speed. Suitable for most building tasks. |
| **Claude Haiku 4.5** | Fast and lightweight. Best for quick edits, simple questions, and routine changes. |
| **GPT-5.1** | Alternative model with different strengths. Useful for getting a second perspective. |
| **Gemini 3 Pro** | Alternative model. Good for varied approaches to problem-solving. |
You can switch models from the model selector in the chat input. Different models consume different amounts of credits — see [Plans & Credits](/getting-started/plans-and-credits) for details.
The AI agent can access data through your connected integrations. When you connect a service like Stripe, Salesforce, or an external database, the agent can read from and write to those services as part of building your app.
The agent only accesses services you have explicitly connected. It cannot access external APIs or databases that have not been configured as integrations in your workspace.
The AI agent has two operating modes:
* **Agent mode** — The agent can create files, edit code, run database queries, connect integrations, and make any modifications to your app. Use this when you want to build or change something.
* **Ask mode** — The agent has read-only access. It can answer questions about your code, explain how something works, and provide suggestions, but it cannot make changes. Use this when you want to understand something without risk of modifying your app.
You can switch between modes at any time from the chat input.
***
## Code & Technical
Yes. Every Vybe app is a standard Next.js 15 project with full source code access. You can view and edit all files through the **Code** tab in the app builder. The codebase is backed by Git, giving you full version history of every change.
You can install packages from the pre-approved list only. Currently approved packages include:
* **Tiptap** — For rich text editing
* **React Flow** — For node-based diagrams and flowcharts
You cannot install arbitrary npm packages. If you need functionality from a package that is not on the approved list, describe what you need to the AI agent and it will implement the feature using the available tools and libraries.
See [Available Packages](/tips/available-packages) for the complete list.
Every Vybe app is a full-stack application built with:
* **Next.js 15** (App Router) with React 19 and TypeScript
* **PostgreSQL** database (dedicated per app)
* **Tailwind CSS** for styling
* **Shadcn UI** component library
* **Prisma** ORM for database access
Apps are deployed to managed infrastructure and served over HTTPS.
See [Tech Stack](/reference/tech-stack) for the full reference.
Vybe does not support WebSockets or Server-Sent Events for real-time communication. If your app needs to display frequently changing data, use polling or periodic data refresh instead.
For example, you can set up a page that refreshes data every 30 seconds, or add a manual refresh button that fetches the latest data on demand.
Vybe apps cannot receive inbound webhooks directly. If you need to react to events from external services, use scheduled workflows to poll those services for updates at regular intervals.
For example, instead of receiving a Stripe webhook when a payment is made, you can set up a workflow that checks for new payments every few minutes.
See [Workflows](/workflows/overview) for more on setting up scheduled tasks.
***
## Data & Databases
Each Vybe app comes with its own built-in **PostgreSQL** database. The AI agent creates tables, writes queries, and manages the schema automatically as you build your app.
You can also connect external databases as integrations:
* **PostgreSQL** — Direct connection or via SSH tunnel
* **MySQL** — Direct connection or via SSH tunnel
* **Amazon Redshift** — Direct connection
External database connections are configured at the organization level and available across all apps. You can enable read-only mode for production databases to prevent accidental writes.
See [External Data](/data/external-data) for setup instructions.
Yes. Vybe takes multiple measures to protect your data:
* **Encryption at rest** — All secrets, API keys, and credentials are encrypted before storage
* **Sandboxed environments** — Each app runs in an isolated environment during development
* **HTTPS** — All deployed apps are served over HTTPS with TLS encryption
* **Authentication** — Only authenticated members of your organization can access deployed apps
* **Isolated databases** — Each app has its own dedicated PostgreSQL instance
See the [Security](/security/overview) section for comprehensive details on data protection and encryption.
***
## Integrations
Vybe supports over 3,000 services through its integration platform. These include major SaaS tools like Slack, Salesforce, Jira, Stripe, HubSpot, Google Workspace, and many more.
For services without a built-in integration, you can create a **Custom API** connection that works with any REST service using key or token authentication.
See [All Integrations](/integrations/all-integrations) for the complete list.
Yes. Integrations are connected at the organization level and available across all apps in your workspace. When you connect Stripe, for example, every app in your organization can use that Stripe connection.
Individual integrations have visibility settings — you can make a connection available to the whole organization or keep it private to your account.
***
## Collaboration & Teams
Team members can be invited to your organization with different roles:
| Role | Capabilities |
| ---------- | ---------------------------------------------------------- |
| **Owner** | Full access. Manage billing, members, and all apps. |
| **Admin** | Manage members and all apps. Cannot modify billing. |
| **Editor** | Create and edit apps. Cannot manage members. |
| **Member** | View and use deployed apps. Limited building capabilities. |
Apps can be shared with the whole organization or restricted to specific users. See [Members & Roles](/teams/members-and-roles) for details on permission levels.
No. Vybe apps can only be accessed by authenticated members of your organization. There is no guest access or public sharing.
If you need to give someone access to an app, invite them to your organization first with the appropriate role.
***
## Billing & Credits
AI interactions are paused until your credits reset or you purchase more. On the Free plan, credits reset daily. On Pro and Team plans, credits reset monthly.
While out of credits, you can still:
* Access and use your deployed apps
* Edit code manually in the Code tab
* Manage integrations and organization settings
* Invite and manage team members
On Pro and Team plans, you can purchase additional credits immediately without waiting for the reset. See [Plans & Credits](/getting-started/plans-and-credits) for details.
Here is a quick guide:
* **Free** — You are exploring Vybe, building a personal project, or want to try the platform before committing. You get 100 credits per day.
* **Pro** — Your team actively builds and maintains internal tools. You need 2,000 credits per month and support for multiple Builder and Viewer seats.
* **Team** — Your organization has multiple builders and needs 5,000 credits per month with full team management capabilities.
You can start on the Free plan and upgrade at any time. See [Plans & Credits](/getting-started/plans-and-credits) for a full comparison.
Yes. The Free plan requires no credit card and gives you 1,000 credits on account creation plus 100 credits per day. This is enough to build several apps and evaluate the platform before deciding whether to upgrade.
# The Editor
Source: https://docs.vybe.build/getting-started/interface
Navigate the multi-tab editor interface — preview, code, data, logs, and more
The Vybe editor is your workspace for building apps. It combines a live preview, code browser, database explorer, and real-time logs — all in one interface alongside the AI chat panel.
***
## Editor layout
The editor is split into two main areas:
* **Left panel** — The AI chat, where you send messages and interact with the agent
* **Right panel** — The multi-tab editor with your app's preview, code, data, and more
You can resize the panels by dragging the divider between them. A sidebar on the left provides access to app settings, integrations, and recipe steps (when applicable).
***
## Editor tabs
The editor provides multiple tabs across the top of the right panel. Each tab gives you a different view into your app.
### Preview
The Preview tab shows a live, running version of your app. This is where you see your app exactly as your users will.
* **Auto-refresh** — The preview updates automatically whenever the AI makes changes to your code
* **Page selector** — A dropdown at the top lets you navigate between different pages and routes in your app
* **Runtime errors** — When your app has errors, the preview displays error details. You can copy the error and paste it into the chat for the AI to diagnose and fix
* **Interactive** — You can interact with your app directly in the preview (click buttons, fill forms, navigate between pages)
If the preview shows an error, copy the error message and send it to the AI chat. The AI will diagnose the issue and suggest a fix.
### Code
The Code tab gives you a full view of your app's source code.
* **File explorer** — Browse the complete file tree of your project in the left sidebar
* **Syntax highlighting** — View any file with full syntax highlighting for TypeScript, JSX, CSS, JSON, and more
* **Diff view** — See exactly what the AI changed in each file after a modification
* **Read-only** — The code editor is for viewing only. All code changes are made through the AI chat
You do not edit code directly in the Code tab. The AI is your code editor — describe what you want changed in the chat, and the AI modifies the files for you.
### Data
The Data tab lets you explore and manage your app's database.
* **Schema visualization** — View an entity-relationship diagram (ERD) showing your database tables and their relationships
* **Table browser** — Select any table to view its rows. You can add, edit, and delete rows directly from this interface
* **External databases** — If you have connected external databases, their schemas appear here as well
The Data tab is essential for verifying that your database is structured correctly and that data is flowing as expected.
### Logs
The Logs tab displays real-time output from your development server.
* **Server logs** — See console output from your API routes and server-side code
* **Error tracking** — Runtime errors and exceptions appear here with stack traces
* **Debugging** — Use this tab to debug server-side issues, inspect API responses, and verify that your backend logic works correctly
When debugging API routes or server-side logic, keep the Logs tab open alongside the Preview tab. You will see server output in real-time as you interact with your app.
### Analytics
The Analytics tab shows page visit tracking for deployed apps.
* **Page views** — See which pages your users visit most frequently
* **Usage patterns** — Understand how your team uses the app after deployment
Analytics data is available once your app is deployed and being accessed by users.
### Workflows
The Workflows tab appears when workflows are enabled for your app.
* **Background jobs** — View and manage background tasks
* **Scheduled tasks** — Monitor recurring jobs and their execution history
* **Job status** — See which workflows are running, completed, or failed
### External DB Queries
The External DB Queries tab shows a history of queries executed against connected external databases.
* **Query log** — Review past queries, their results, and execution times
* **Debugging** — Verify that external database queries return the expected data
***
## The sidebar
The left sidebar provides quick access to app configuration:
| Section | Description |
| ---------------- | ----------------------------------------------------------------- |
| **App settings** | Rename your app, set custom instructions, configure access levels |
| **Integrations** | View and manage connected services and databases for this app |
| **Recipe steps** | When building from a recipe, the guided setup steps appear here |
***
## The chat panel
The chat panel occupies the left portion of the editor. It includes:
* **Message input** — Where you type prompts and instructions for the AI
* **Model selector** — Switch between AI models (Opus 4.5, Sonnet 4.5, etc.)
* **Mode toggle** — Switch between Agent mode (can modify) and Ask mode (read-only)
* **Image attachment** — Upload screenshots or images to include with your message
* **Thread selector** — Switch between conversation threads or create new ones
* **Suggestions** — Contextual next-step suggestions appear after the AI completes a task
***
## Resizing panels
You can customize the editor layout to match your workflow:
* **Drag the divider** between the chat panel and editor panel to adjust their relative sizes
* **Open multiple tabs** to quickly switch between preview, code, and data views
* **Focus on chat** by making the editor panel smaller when you are prompting
* **Focus on preview** by making the chat panel smaller when reviewing your app
***
## What's next
* Understand the live preview environment: [Preview & Sandbox](/building-apps/preview-and-sandbox)
* Learn about the generated code structure: [Working with Code](/building-apps/working-with-code)
* Start building: [Creating an App](/building-apps/creating-an-app)
# Plans & Credits
Source: https://docs.vybe.build/getting-started/plans-and-credits
Understand Vybe pricing tiers, how credits work, and how to manage your usage
Vybe uses a credit-based pricing model. Every AI interaction — sending a message, generating code, running a database query through the agent — consumes credits. Your plan determines how many credits you receive and how often they reset.
***
## Plans
Vybe offers three pricing tiers:
| | **Free** | **Pro** | **Team** |
| -------------------- | --------------------------- | ---------------- | -------------------- |
| **Credits** | 100/day | 2,000/month | 5,000/month |
| **Starting balance** | 1,000 on account creation | 2,000/month | 5,000/month |
| **Max balance** | 2,000 | Based on plan | Based on plan |
| **Credit reset** | Daily | Monthly | Monthly |
| **Seat types** | Single user | Builder + Viewer | Builder + Viewer |
| **Buy more credits** | No | Yes | Yes |
| **Best for** | Trying Vybe, small projects | Growing teams | Larger organizations |
You can start building on the Free plan immediately — no credit card required. Upgrade to Pro or Team when you need more credits or team collaboration features.
***
## How credits work
Credits are consumed each time you interact with the AI agent. This includes:
* Sending a message in a thread
* Asking the agent to generate or modify code
* Running database queries through the agent
* Requesting explanations or debugging help
Actions that do **not** consume credits:
* Editing code manually in the Code tab
* Deploying your app
* Managing integrations and settings
* Inviting team members
### Credit reset schedule
| Plan | Reset frequency | Behavior |
| -------- | --------------- | --------------------------------------------------------------------------------------------- |
| **Free** | Daily | You receive 100 credits each day. Unused credits carry over up to a maximum balance of 2,000. |
| **Pro** | Monthly | You receive 2,000 credits at the start of each billing cycle. |
| **Team** | Monthly | You receive 5,000 credits at the start of each billing cycle. |
***
## Credit costs by model
Different AI models consume different amounts of credits per interaction. More powerful models produce higher-quality results but cost more credits.
| Model | Relative cost | Best for |
| --------------------- | ------------- | ------------------------------------------------------------- |
| **Claude Opus 4.5** | Highest | Complex app generation, multi-step reasoning, large refactors |
| **Claude Sonnet 4.5** | Medium-high | General-purpose building, good balance of quality and speed |
| **Claude Haiku 4.5** | Low | Quick edits, simple questions, routine modifications |
| **GPT-5.1** | Medium-high | Alternative perspective, specific coding patterns |
| **Gemini 3 Pro** | Medium | Alternative perspective, different model strengths |
You can switch models at any time from the model selector in the chat input. Choose a lighter model for simple tasks to conserve credits, and a more powerful model when you need complex reasoning.
***
## Seat types
Pro and Team plans use seat-based pricing with two seat types:
| Seat type | Permissions | Consumes credits |
| ----------- | ---------------------------------------------------------------- | ---------------- |
| **Builder** | Create apps, edit code, use AI chat, deploy, manage integrations | Yes |
| **Viewer** | View deployed apps, access app UIs | No |
Builder seats are for team members who actively create and modify apps. Viewer seats are for stakeholders, managers, or team members who only need to use the finished apps.
Use Viewer seats for team members who only need access to deployed apps. This keeps costs down while giving your whole team access to the tools you build.
***
## Buying more credits
On Pro and Team plans, you can purchase additional credits when your monthly allocation runs out.
Click your organization name in the sidebar and select **Settings**.
Go to the **Billing** tab.
Click **Buy Credits** and select the amount you need. Additional credits are charged to your payment method on file.
Additional credits do not expire at the end of your billing cycle — they remain available until used.
The Free plan does not support purchasing additional credits. Upgrade to Pro or Team if you need more than the daily free allocation.
***
## Checking your usage
You can view your current credit balance and usage history at any time:
1. Click your organization name in the sidebar.
2. Select **Settings**.
3. Open the **Billing** tab.
The billing page shows:
* Your current credit balance
* Credits consumed in the current period
* Usage breakdown by model
* Billing cycle dates and next reset
***
## Upgrading your plan
You can upgrade from Free to Pro or Team at any time:
Click your organization name in the sidebar and select **Settings**.
Navigate to the **Billing** tab.
Choose **Pro** or **Team** and follow the prompts to enter your payment information and select your seat count.
When you upgrade:
* Your new credit allocation is available immediately
* You keep any remaining credits from your previous plan
* Billing starts from the date of upgrade
***
## Frequently asked questions
AI interactions are paused until your credits reset. On the Free plan, credits reset daily. On Pro and Team, credits reset monthly — or you can purchase additional credits immediately.
You can still access your deployed apps, edit code manually, and manage settings while out of credits.
On the Free plan, unused credits carry over up to a maximum balance of 2,000. On Pro and Team plans, unused credits do not roll over — your balance resets at the start of each billing cycle.
Yes. You can downgrade at any time from your billing settings. The downgrade takes effect at the end of your current billing cycle. Your apps and data are preserved regardless of your plan.
Go to **Settings** > **Billing** and adjust your seat count. You can add or remove Builder and Viewer seats at any time. Changes are prorated for the current billing period.
# Quick Start
Source: https://docs.vybe.build/getting-started/quick-start
Build your first Vybe app in four steps — from prompt to deployed internal tool
Welcome to Vybe — your AI-powered internal tool builder that turns text prompts into fully functional business apps.
This guide walks you through building your first app: from describing what you need to deploying a live tool your team can use.
***
## Step 1. Create your first app
Go to your [Vybe dashboard](https://vybe.build/apps) and click **New App**. Give it a name (e.g., `Chargeback Tracker`).
In the chat panel, tell the AI what your app should do. Be specific about what data the app works with, what actions users can take, and what the UI should look like. For example:
> Build an app to manage chargebacks. Show a table of Stripe disputes with status, amount, and customer info. Let my team add notes to each dispute and mark them as resolved.
Click **Send**. The AI generates your full application — database schema, pages, components, and API routes. You can follow along in the [Preview tab](/getting-started/interface) as the app takes shape.
Your prompt is the blueprint of your app. The more specific you are about data, actions, and layout, the better the result. See [Prompting Best Practices](/tips/prompting) for strategies that work well.
***
## Step 2. Connect your data
Most internal tools need data from the services your team already uses.
Navigate to **Integrations** in the left sidebar of your dashboard.
Find your service from over 3,000 supported integrations — Slack, HubSpot, Jira, Stripe, Salesforce, Google Sheets, and more. Click **Connect** and authorize access.
Once connected, tell the AI to use the integration in your app:
> Pull in our open Stripe disputes and display them in the chargebacks table.
Vybe syncs data in real time — no import/export steps needed.
You can also connect external databases (PostgreSQL, MySQL, Amazon Redshift) directly. See [External Databases](/data/external-data) for details.
***
## Step 3. Test and iterate
Switch to the **Preview** tab to interact with your app as a user would. Click through pages, fill out forms, and test workflows.
Send additional messages to adjust anything:
> Add a filter dropdown to show only disputes over \$500. Also add a "Last Updated" column to the table.
The AI updates your app while preserving everything that already works.
If a task is particularly complex, switch to **Opus 4.5 - High** for deeper reasoning. For quick tweaks, **Sonnet 4.5** or **Haiku 4.5** are faster and more cost-effective. See [Choosing a Model](/building-apps/choosing-a-model).
***
## Step 4. Deploy
Click the **Deploy** button in the top navigation bar. Vybe builds and deploys your app to a dedicated URL.
Your app is live at `appname-orgname.vybe.build`. All members of your organization with the right [access level](/teams/app-access) can use it immediately.
Deployments are instant and automatic. Each deploy creates a new version — you can [roll back](/building-apps/version-history) at any time if something goes wrong.
***
## What's next?
Understand the key building blocks: organizations, apps, threads, and more.
Tour the multi-tab editor where you build, preview, and debug your apps.
Learn strategies for writing prompts that get the best results from the AI.
Connect your CRM, database, and other tools to power your apps.
# Welcome to Vybe
Source: https://docs.vybe.build/index
Build internal tools with AI — describe what you need and Vybe builds it for you
Vybe is an AI-powered platform for building internal tools. Describe what you need in plain language, and Vybe builds it — complete with databases, integrations, and deployment.
No boilerplate. No drag-and-drop builders. Just tell the AI what your team needs and get a working application in minutes.
***
## Who is Vybe for?
Vybe is built for anyone who needs internal tools but does not want to spend weeks building them from scratch.
| Role | How you use Vybe |
| ----------------------- | ------------------------------------------------------------------------------------- |
| **Operations teams** | Build dashboards to track KPIs, manage workflows, and triage issues |
| **Engineering teams** | Spin up admin panels, data explorers, and internal APIs without side-project overhead |
| **Business analysts** | Create reporting tools and data visualizations connected to live data sources |
| **Founders & managers** | Build CRM interfaces, approval workflows, and team management tools |
***
## What can you build?
Vybe apps are full-stack Next.js 15 applications with their own PostgreSQL database, connected integrations, and production deployment. Common use cases include:
* **Dashboards** — Real-time views of metrics from Stripe, HubSpot, your database, or any connected service
* **Admin panels** — CRUD interfaces for managing users, content, orders, or any entity
* **CRM tools** — Customer management with data pulled from Salesforce, HubSpot, or custom databases
* **Data explorers** — Query and visualize data across multiple sources in one interface
* **Workflow automation** — Approval flows, triage queues, and task management connected to Slack, Jira, and more
* **Reporting tools** — Scheduled reports and analytics dashboards powered by live data
***
## How it works
Tell the AI what you want to build. Be specific about the data sources, features, and workflows your team needs.
> I need a chargeback tracker that pulls disputes from Stripe, shows them in a sortable table, and lets my team assign each dispute to a reviewer.
The AI agent creates your app — generating pages, database tables, API routes, and integration connections. Watch the app take shape in real time through the live preview.
Click **Deploy** to publish your app. Your team can access it immediately at a production URL. Only authenticated members of your organization can view your apps.
***
## Key capabilities
Chat with an AI agent that writes code, creates database schemas, connects APIs, and builds complete user interfaces — all from your descriptions.
Connect to Slack, Salesforce, Jira, Stripe, HubSpot, Google Workspace, and thousands more. Plus direct database connections to PostgreSQL, MySQL, and Redshift.
Every app gets its own PostgreSQL database. The AI creates tables, writes queries, and manages migrations. You can also connect external databases.
Deploy your app to a production URL with a single click. Apps run on managed infrastructure with HTTPS, authentication, and automatic scaling.
Invite team members to your organization with role-based permissions. Control who can build, edit, and view each app.
Choose from Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, GPT-5.1, and Gemini 3 Pro. Switch models at any time based on your needs.
***
## Get started
Build your first app in under 5 minutes.
Understand the key building blocks of Vybe.
Learn how to communicate effectively with the AI agent.
Connect your existing tools and data sources.
# All Integrations
Source: https://docs.vybe.build/integrations/all-integrations
Browse all available integrations and their capabilities
Vybe connects to over 3,000 apps through its integration platform. This page highlights common integrations with pre-built data models and actions. For the complete list, browse the [full integration catalog](https://www.vybe.build/integrations).
Each integration lists its available capabilities as **read** (pull data into your app) or **write** (push data or trigger actions).
***
## CRM & Sales
Connect to HubSpot to access your CRM data and manage deals.
| Capability | Type |
| ------------------ | ----- |
| View Companies | Read |
| View Contacts | Read |
| View Deals | Read |
| Create/Update Deal | Write |
| Delete Deal | Write |
| View Users | Read |
Connect to Salesforce to access accounts, contacts, leads, opportunities, and custom objects.
| Capability | Type |
| --------------------------- | ----- |
| View Accounts | Read |
| Create/Update Account | Write |
| View Contacts | Read |
| View Custom Fields | Read |
| Update Custom Field | Write |
| View Custom Object Records | Read |
| Create Custom Object Record | Write |
| View Leads | Read |
| Create/Update Lead | Write |
| View Opportunities | Read |
| Create/Update Opportunity | Write |
| View Campaigns | Read |
| View Tickets | Read |
Connect to Attio for lightweight CRM data access.
| Capability | Type |
| -------------- | ---- |
| View People | Read |
| View Companies | Read |
| View Deals | Read |
| View Objects | Read |
| View Records | Read |
***
## Project Management
Connect to Jira to view and create issues across your projects.
| Capability | Type |
| ---------------- | ----- |
| View Projects | Read |
| View Issues | Read |
| View Issue Types | Read |
| Create Issue | Write |
After connecting Jira, open the integration settings to select which projects to sync.
Connect to Linear to access your project and issue data.
| Capability | Type |
| ------------- | ---- |
| View Projects | Read |
| View Teams | Read |
| View Users | Read |
| View Issues | Read |
Connect to Asana to access projects, tasks, and workspace data.
| Capability | Type |
| ---------------------------- | ---- |
| View Projects | Read |
| View Project Tasks | Read |
| View Users | Read |
| View Tasks | Read |
| View Workspaces | Read |
| View Workspace Custom Fields | Read |
Connect to Shortcut to access epics, members, and objectives.
| Capability | Type |
| --------------- | ---- |
| View Epics | Read |
| View Members | Read |
| View Groups | Read |
| View Objectives | Read |
Connect to ClickUp to manage tasks, goals, and custom fields.
| Capability | Type |
| ---------------------- | ----- |
| View Goals | Read |
| View Folders | Read |
| View Spaces | Read |
| View Tasks | Read |
| Create/Update Task | Write |
| View Custom Task Types | Read |
| View Lists | Read |
| View List Members | Read |
| View Custom Fields | Read |
***
## Communication
Connect to Slack to access channels, messages, and send notifications.
| Capability | Type |
| ---------------------- | ----- |
| View Users | Read |
| View Channels | Read |
| Create Channel | Write |
| View Messages | Read |
| View Message Replies | Read |
| View Message Reactions | Read |
| Send Message as bot | Write |
| Send Message as user | Write |
Connect to Intercom to access customer conversations and contact data.
| Capability | Type |
| -------------------------- | ---- |
| View Contacts | Read |
| View Conversations | Read |
| View Conversation Messages | Read |
Connect to Gmail to view and send emails.
| Capability | Type |
| ----------- | ----- |
| View Emails | Read |
| Send Email | Write |
***
## Developer Tools
Connect to GitHub to access repositories, pull requests, and commits.
| Capability | Type |
| ------------------ | ---- |
| View Repositories | Read |
| View Pull Requests | Read |
| View Commits | Read |
Connect to GitLab to access projects and merge requests.
| Capability | Type |
| ------------------- | ---- |
| View Projects | Read |
| View Merge Requests | Read |
Connect to PostHog for product analytics and custom queries.
| Capability | Type |
| ------------- | ----- |
| View Projects | Read |
| Send QL Query | Write |
After connecting PostHog, open the integration settings to configure your PostHog Project ID.
Connect to Notion to access pages, databases, and content.
| Capability | Type |
| -------------------- | ---- |
| View Contents | Read |
| View Single Content | Read |
| View Users | Read |
| View Databases | Read |
| View Single Database | Read |
| View Rich Page | Read |
***
## Productivity
Connect to Google Calendar to view and manage events.
| Capability | Type |
| ------------------- | ----- |
| View Events | Read |
| Create/Update Event | Write |
Connect to Google Ads to access campaign and ad performance data.
| Capability | Type |
| --------------------------------- | ---- |
| View Campaign Performance Metrics | Read |
| View Ad Group Performance Metrics | Read |
| View Ad Performance Metrics | Read |
| View Keyword Performance Metrics | Read |
***
## Billing & Subscriptions
Connect to Stripe to access subscription, customer, product, and invoice data.
| Capability | Type |
| ------------------ | ---- |
| View Subscriptions | Read |
| View Customers | Read |
| View Products | Read |
| View Invoices | Read |
Connect to Chargebee to access subscription and customer data.
| Capability | Type |
| ------------------ | ---- |
| View Subscriptions | Read |
| View Customers | Read |
| View Entitlements | Read |
***
## Marketing & Outreach
Connect to SmartLead AI to access campaign data and analytics.
| Capability | Type |
| ------------------------ | ---- |
| View Campaigns | Read |
| View Campaign Analytics | Read |
| View Campaign Leads | Read |
| View Campaign Statistics | Read |
| View Clients | Read |
| View Leads Categories | Read |
Connect to Lemlist to manage outreach campaigns and leads.
| Capability | Type |
| -------------------- | ----- |
| View Campaigns | Read |
| View Campaign Stats | Read |
| Add Lead to Campaign | Write |
***
## Built-in Integrations
These integrations are always available and require no setup.
Enrich contacts with professional data using email addresses. Returns job titles, companies, social profiles, and more.
Enrich data using LinkedIn profile URLs. Returns detailed professional and company information.
Extract email addresses from LinkedIn profile URLs.
Access generative AI capabilities with optional web search for enriching app data and automating text-based tasks.
***
## Databases
Connect directly to external databases for live data access in your apps.
| Database | Features |
| ------------------- | --------------------------------------------------- |
| **PostgreSQL** | Full SQL access, read-only mode, SSH tunnel support |
| **MySQL** | Full SQL access, read-only mode, SSH tunnel support |
| **Amazon Redshift** | Full SQL access with IAM role-based authentication |
For setup instructions, see [Integration Basics — Connecting a database](/integrations/integration-basics#connecting-a-database).
***
## Don't see your integration?
Vybe supports over 3,000 apps through the Pipedream integration platform. Search for any app on the Integrations page in your workspace. You can also use **Custom APIs** to connect to any REST API with key or token authentication. See [Integration Basics — Custom APIs](/integrations/integration-basics#custom-apis) for details.
# Custom APIs
Source: https://docs.vybe.build/integrations/custom-apis
Store API credentials securely in Vybe for services without a built-in integration
For services that do not have a built-in integration, you can store API credentials as a Custom API in Vybe. This gives your apps secure access to any REST API — and gives the AI context about the service so it can generate the right code.
***
## When to use Custom APIs
Use Custom APIs when:
* The service you need is not in the [integrations catalog](/integrations/all-integrations)
* You have an internal API that your apps need to call
* You want to manage API credentials centrally instead of hardcoding them
* You need the AI to understand how to call a specific API
Custom APIs store your credentials securely and inject them as environment variables into your app's server-side code.
***
## Authentication types
Custom APIs support three authentication methods:
| Type | Header format | Use case |
| ---------------- | ---------------------------------------- | -------------------------------------------------- |
| **API Key** | `X-API-Key: sk_123abc` | Services that use a single API key |
| **Bearer Token** | `Authorization: Bearer token123` | OAuth tokens, JWT tokens, or similar |
| **Basic Auth** | `Authorization: Basic base64(user:pass)` | Services that use username/password authentication |
Choose the type that matches how the target API expects to receive credentials.
***
## Creating a Custom API
Navigate to **Integrations** in the left sidebar and scroll to the **Custom APIs** section.
Click **Create Custom API** to open the creation form.
Fill in the following fields:
| Field | Required | Description |
| --------------------- | -------- | --------------------------------------------------------------------------- |
| **Name** | Yes | A descriptive name for the API (e.g., "Internal Billing API", "Twilio SMS") |
| **Auth type** | Yes | API Key, Bearer Token, or Basic Auth |
| **Credentials** | Yes | The actual key, token, or username/password |
| **Domain** | No | Associate the API with a specific domain (e.g., `api.example.com`) |
| **Documentation URL** | No | Link to the API's documentation so the AI can reference it |
Select who can use this Custom API:
* **Organization** — Available to all members and all apps in your workspace
* **App-specific** — Available only to a specific app
Click **Save**. The credentials are encrypted and stored securely. After saving, credential values are masked in the UI and cannot be viewed again.
***
## Environment variable injection
Each Custom API automatically gets an environment variable name based on the API name. For example:
| Custom API name | Environment variable |
| --------------------- | ---------------------------------- |
| My Billing API | `CUSTOM_API_MY_BILLING_API` |
| Twilio SMS | `CUSTOM_API_TWILIO_SMS` |
| Internal Auth Service | `CUSTOM_API_INTERNAL_AUTH_SERVICE` |
The variable contains the credential value (API key, bearer token, or base64-encoded basic auth string).
***
## Using Custom APIs in code
Access your Custom API credentials through environment variables in server-side code. The AI generates code like this when it knows about your Custom API:
```typescript theme={null}
export async function GET() {
const response = await fetch('https://api.example.com/data', {
headers: {
'Authorization': `Bearer ${process.env.CUSTOM_API_MY_SERVICE}`,
'Content-Type': 'application/json',
},
});
const data = await response.json();
return Response.json(data);
}
```
Custom API credentials are only available in server-side code (API routes and server components). They are never exposed to the browser.
***
## Associating documentation
You can link API documentation to a Custom API so the AI can reference it when building features. This is particularly useful for complex APIs with many endpoints.
When you provide a documentation URL:
* The AI reads the documentation to understand the available endpoints, request formats, and response structures
* The AI generates more accurate code because it knows the exact API contract
* You spend less time correcting the AI's assumptions about the API
If the API has an OpenAPI/Swagger spec, consider using [OpenAPI Client Generation](/integrations/openapi-client) instead for fully typed access.
***
## Security
Custom API credentials are protected with several security measures:
* **Encrypted at rest** — Credentials are encrypted before being stored in the database
* **Masked in the UI** — After creation, credential values are hidden and cannot be retrieved through the interface
* **Server-side only** — Credentials are injected as server-side environment variables and never sent to the browser
* **Scoped access** — Organization-scoped APIs are available to all workspace members; app-specific APIs are restricted to a single app
***
## Managing Custom APIs
From the Custom APIs section on the Integrations page, you can:
* **Edit** — Update the name, domain, documentation URL, or scope. To change credentials, delete and recreate the Custom API.
* **Delete** — Remove the Custom API. Apps that reference the environment variable will lose access to the credentials.
* **View** — See the API name, type, scope, and associated domain. Credential values are always masked.
If you need to rotate credentials, delete the existing Custom API and create a new one with the updated credentials. The environment variable name will remain the same if you use the same API name.
# Integration Basics
Source: https://docs.vybe.build/integrations/integration-basics
Connect your existing tools and data sources to power your Vybe apps
Integrations let your Vybe apps read and write data from the tools your team already uses — CRMs, project trackers, communication platforms, databases, and more.
Once connected, integrations are available across all apps in your workspace. Vybe syncs data in real time, so your apps always reflect the latest information.
***
## Integration types
Vybe supports several categories of integrations:
| Type | Description | Examples |
| ---------------- | -------------------------------------------------------- | ----------------------------------- |
| **Services** | Third-party SaaS apps connected via OAuth or API keys | Slack, HubSpot, Jira, Salesforce |
| **Built-in** | Always-on integrations that require no setup | People Data Labs, CrustData, OpenAI |
| **Databases** | Direct connections to external databases | PostgreSQL, MySQL, Amazon Redshift |
| **Custom APIs** | Manually configured API credentials for any REST service | Any API with key or token auth |
| **Data Queries** | Saved queries against connected data sources | SQL queries, API-specific queries |
***
## How to connect integrations
There are two ways to connect integrations in Vybe:
### From within the editor (recommended)
The easiest way to connect an integration is directly from the app you're building. Click the **+** button next to your connected integrations in the chat panel (bottom left, next to the integration icons). This opens the integration picker without leaving your current context.
### From the Integrations page
You can also manage all integrations from the central **Integrations** page in the left sidebar. This is useful for:
* Browsing all 3,000+ available services
* Managing existing connections across your workspace
* Configuring organization-wide integrations before building apps
You can connect the same service multiple times with different accounts — for example, connecting both a personal and team Slack workspace.
***
## Visibility settings
Each integration connection has a visibility setting that controls who in your workspace can use it:
* **Organization** — Available to all members of your workspace. Use this for shared team accounts.
* **You only** — Only visible to you. Use this for personal accounts or sensitive credentials.
To change visibility, click the visibility dropdown on the integration card and select your preference.
Visibility controls who can *use* the connection in their apps. Only the person who created the connection (or an admin) can delete it.
***
## Connecting a database
Vybe supports direct connections to external databases, letting your apps query live production or analytics data.
Navigate to **Integrations** in the left sidebar and scroll to the **Databases** section.
Select your database type: **PostgreSQL**, **MySQL**, or **Amazon Redshift**.
Provide the connection string or individual credentials (host, port, database name, username, password).
Optionally enable **read-only mode** to prevent accidental writes, or **SSH tunnel** to connect through a firewall.
Vybe validates the connection before saving. If using an SSH tunnel, make sure the SSH key is added under the **SSH Keys** section first.
Database connections are organization-wide. All workspace members can query connected databases. Enable **read-only mode** for production databases to prevent accidental modifications.
***
## Custom APIs
For services without a built-in integration, you can store API credentials as Custom APIs.
1. In the **Integrations** page, scroll to **Custom APIs**.
2. Click **Create Custom API**.
3. Enter the API name, authentication type (API key, Bearer token, etc.), and credentials.
4. Optionally add documentation and scope the API to specific apps.
Custom API credentials are stored securely and masked in the UI after creation.
***
## SSH keys
SSH keys enable secure tunneled connections to databases behind firewalls or private networks.
1. In the **Integrations** page, scroll to **SSH Keys**.
2. Click **Create SSH Key** to generate a new key pair.
3. Copy the public key and add it to your server's `authorized_keys`.
4. When connecting a database, select the SSH key and provide the tunnel endpoint.
SSH keys can be reused across multiple database connections.
***
## Data queries
Data queries let you save and reuse queries against your connected integrations and databases.
1. In the **Integrations** page, scroll to **Data Queries**.
2. Click **Create Data Query**.
3. Select the data source (a connected service or database).
4. Write and name your query.
Saved queries are available organization-wide and can be referenced from any app in your workspace.
***
## Using integrations in apps
Once connected, integrations become available when building apps. When you describe what your app should do in a prompt, Vybe automatically identifies which connected integrations are relevant and wires them into your app.
You can also manually select integrations when configuring app data sources and actions.
***
## Managing integrations
From the integration card on the Integrations page, you can:
* **Explore data** — Browse available tables, objects, and records from the connected service.
* **Edit settings** — Configure integration-specific options (e.g., which Jira projects to sync, PostHog project ID).
* **Change visibility** — Toggle between organization and personal access.
* **Delete** — Remove the connection. This does not delete data already used in apps, but apps will lose access to future syncs.
# OpenAPI Client Generation
Source: https://docs.vybe.build/integrations/openapi-client
Generate fully typed TypeScript API clients from OpenAPI and Swagger specifications
If you have an API with an OpenAPI (Swagger) specification, the AI can generate a fully typed TypeScript client for it. This gives your Vybe app type-safe access to every endpoint in the API, with auto-complete and compile-time validation.
***
## When to use this
Use OpenAPI client generation when:
* Your API has an OpenAPI 2.0 (Swagger) or OpenAPI 3.x specification
* The API has many endpoints and you want type-safe access to all of them
* You want the AI to understand the full API surface so it can generate accurate code
* You have an internal service with a published spec
For simpler APIs with just a few endpoints, a [Custom API](/integrations/custom-apis) with environment variable injection may be enough.
| Approach | Best for |
| ------------------ | ---------------------------------------------------------------------------------------- |
| **OpenAPI client** | Complex APIs with many endpoints, typed requests/responses, internal services with specs |
| **Custom API** | Simple key-based access, APIs with a few endpoints, services without an OpenAPI spec |
***
## How it works
Tell the AI where to find your API's OpenAPI specification. You can either:
* **Share a URL**: Give the AI the URL to your spec (e.g., `https://api.example.com/openapi.json`)
* **Paste the spec**: Copy and paste the YAML or JSON spec directly into the chat
> Generate a typed API client from this OpenAPI spec: [https://api.example.com/openapi.json](https://api.example.com/openapi.json)
The AI reads the specification and generates a TypeScript client that includes:
* **Type definitions** for all request and response schemas
* **Client functions** for every endpoint in the spec
* **Authentication handling** using your configured credentials
* **Error types** for documented error responses
The generated client is added to your app's codebase. The AI uses it when building features that call the API, giving you full type safety.
***
## What gets generated
The AI generates a client tailored to your API's specification. A typical generated client includes:
### Type-safe request and response types
Every endpoint's request body, query parameters, path parameters, and response type are defined as TypeScript interfaces. This means your editor provides auto-complete and the compiler catches type mismatches.
### Endpoint functions
Each API endpoint becomes a typed function. For example, an API with a `GET /users/{id}` endpoint would get a function like:
```typescript theme={null}
// The AI generates typed functions for each endpoint
const user = await apiClient.getUser({ id: 'user-123' });
// user is fully typed with all fields from the API response
```
### Authentication handling
The client includes authentication based on the spec's security definitions. If your API uses Bearer tokens, API keys, or OAuth, the generated client handles the headers automatically using your configured credentials.
***
## Example workflow
Here is a typical workflow for using OpenAPI client generation:
1. **You**: "I have an internal inventory API at [https://inventory.internal.io](https://inventory.internal.io). Here is the OpenAPI spec: \[paste or URL]"
2. **AI**: Reads the spec, identifies the endpoints, and generates a typed client.
3. **You**: "Build a page that shows all products with low stock and lets me reorder them."
4. **AI**: Uses the generated client to call the `GET /products?stock_level=low` endpoint and the `POST /orders` endpoint, with full type safety.
Because the AI has the complete API specification, it knows exactly which endpoints are available, what parameters they accept, and what the responses look like. This means fewer errors and more accurate code generation.
***
## Updating the client
If your API spec changes — new endpoints, updated schemas, or modified parameters — you can ask the AI to regenerate the client:
> The inventory API spec has been updated. Regenerate the TypeScript client from [https://inventory.internal.io/openapi.json](https://inventory.internal.io/openapi.json)
The AI will update the generated types and functions to match the new spec. Any app code that uses removed or changed endpoints will surface as TypeScript errors, making it easy to identify what needs to be updated.
***
## Combining with Custom APIs
You can use OpenAPI client generation together with Custom APIs. A common pattern is:
1. **Create a Custom API** to securely store your API credentials (API key, Bearer token, etc.)
2. **Generate an OpenAPI client** for type-safe endpoint access
3. The generated client uses the Custom API's environment variable for authentication
This gives you both secure credential management and typed API access.
If your API requires authentication, set up a Custom API for the credentials before generating the OpenAPI client. The AI will wire them together automatically.
***
## Supported specifications
The AI can generate clients from:
| Format | Versions |
| ----------- | ------------ |
| **OpenAPI** | 3.0.x, 3.1.x |
| **Swagger** | 2.0 |
Both JSON and YAML formats are supported. The spec can be provided as a URL or pasted directly into the chat.
***
## Limitations
* **Server-side only** — Generated clients are used in API routes and server components. They cannot be called from client-side code.
* **REST APIs** — OpenAPI client generation works with REST APIs. For GraphQL APIs, the AI can generate queries directly without a client generator.
* **Spec quality matters** — The accuracy of the generated client depends on the quality of the OpenAPI spec. Specs with incomplete type definitions or missing endpoint documentation will produce less useful clients.
# Using Integrations in Chat
Source: https://docs.vybe.build/integrations/using-in-chat
How the AI uses your connected integrations to fetch data, take actions, and build features during a conversation
When you chat with the AI in Vybe, it can access your connected integrations to fetch data, execute actions, and wire up your app to external services. You describe what you need in plain language, and the AI figures out which integration to use and how.
***
## How it works
The AI has access to all integrations connected to your organization (and your personal connections). When you describe what you need, the AI:
1. **Identifies the relevant integration** — Based on your prompt, the AI determines which connected service has the data or action you need.
2. **Selects the right action** — Each integration exposes a set of actions (like "list issues" or "send message"). The AI picks the appropriate one.
3. **Executes the action** — The AI runs the integration action and returns the results directly in the chat.
You do not need to specify which integration to use or how to call it. The AI handles the details.
***
## Examples
Here are common ways you can use integrations through the chat:
### Fetching data
> Show me all open Jira tickets assigned to the engineering team.
The AI uses the Jira integration to query your projects, filters for open tickets assigned to engineering, and displays the results in a formatted table.
> Pull our last 30 days of Stripe charges and display them in a table.
The AI uses the Stripe integration to fetch recent charges, then presents them in a sortable table with amount, customer, status, and date columns.
> What are our top-performing Google Ads campaigns this month?
The AI queries the Google Ads integration for campaign performance metrics and summarizes the results.
### Taking actions
> Create a Slack channel called "project-apollo" and invite the engineering team.
The AI uses the Slack integration to create the channel and send invitations.
> Create a new Jira issue in the Backend project: "Fix login timeout bug", priority High, assigned to Sarah.
The AI creates the issue in Jira with the specified details and confirms the result.
> Send an email to the team with this week's sales summary.
The AI uses the Gmail integration to compose and send the email.
### Exploring available data
> What data can I get from HubSpot?
The AI lists the available capabilities for your HubSpot connection — contacts, companies, deals, and more — so you know what is available before you build.
> Show me the fields available in our Salesforce Leads object.
The AI queries your Salesforce connection and displays the field names, types, and descriptions.
***
## Connecting integrations on the fly
If you ask the AI to use a service that is not connected yet, it will prompt you to connect it. A button appears in the chat that takes you directly to the authorization flow for that service.
For example, if you say:
> Show me our Linear issues.
And Linear is not connected, the AI will respond with a message explaining that Linear needs to be connected, along with a button to set up the connection. Once you authorize the integration, you can continue the conversation and the AI will use it immediately.
***
## Integration visibility
The AI can only use integrations you have access to. Visibility depends on how the integration was connected:
| Visibility | Who can use it |
| ---------------- | -------------------------------- |
| **Organization** | All members of your workspace |
| **You only** | Only the person who connected it |
If you cannot see an integration in the chat, check the Integrations page to verify it is connected and that its visibility includes you. Organization-level integrations are available to everyone; personal integrations are only available to the person who connected them.
When building features that other team members will use, connect integrations with **Organization** visibility so the AI can access them in anyone's chat session.
***
## What the AI can do with integrations
The AI's capabilities depend on the actions each integration exposes. In general:
| Capability | Description |
| ----------- | ------------------------------------------------------------------ |
| **Search** | Find records matching specific criteria |
| **List** | Retrieve collections of records (issues, contacts, channels, etc.) |
| **Read** | Get detailed information about a specific record |
| **Create** | Add new records to a service |
| **Update** | Modify existing records |
| **Execute** | Run service-specific actions (send email, trigger workflow, etc.) |
Not every integration supports all capabilities. See [All Integrations](/integrations/all-integrations) for a full list of each service's available actions.
***
## Tips for effective prompts
* **Be specific about what you want.** Instead of "show me Salesforce data," say "show me all Salesforce opportunities closing this quarter with a value over \$50,000."
* **Use @mention to specify an integration.** Type `@` followed by the integration name (e.g., `@Slack` or `@Jira`) to explicitly tell the AI which integration to use. This ensures the AI knows exactly which service you mean, especially when multiple integrations could have similar data.
* **Ask what is available** if you are unsure. Prompts like "what integrations are connected?" or "what can I do with Jira?" help you discover capabilities.
* **Chain actions together.** You can ask the AI to combine multiple integrations in a single request: "Pull open Jira tickets, find the assignees in Slack, and send each person a reminder about their overdue tickets."
# Using Integrations in Code
Source: https://docs.vybe.build/integrations/using-in-code
How the AI generates server-side code that calls integrations from API routes and background workflows
For advanced use cases, the AI can generate server-side code that calls your connected integrations directly from API routes and background workflows. This is useful when you need integration access as part of your app's logic — not just in the chat.
***
## When to use integrations in code
Most of the time, the AI handles integrations for you during the chat. But there are cases where you need integration access baked into your app's code:
| Use case | Example |
| ------------------------ | ----------------------------------------------------------- |
| **Form submissions** | A form that creates a Jira ticket when submitted |
| **API endpoints** | An endpoint that fetches Salesforce contacts for a dropdown |
| **Background workflows** | An Inngest function that syncs HubSpot deals every hour |
| **Data processing** | An API route that enriches leads with People Data Labs data |
| **Notifications** | Sending a Slack message when a record changes |
In these cases, the AI generates code that calls integrations from the server side, so the logic runs automatically without user interaction in the chat.
***
## How it works
You describe what you need, and the AI writes the code. For example:
> When someone submits the new ticket form, create a Jira issue in the Backend project with the form data.
The AI generates an API route that:
1. Receives the form submission
2. Calls the Jira integration to create an issue
3. Returns the created issue details to the frontend
Under the hood, the AI uses `runIntegrationActionFromServer()` to execute integration actions from server-side code. You do not need to call this function directly or understand its API — the AI handles the implementation.
Only **organization-level** integrations are accessible from server-side code. Personal integrations (set to "You only" visibility) cannot be used in generated app code, because the app runs for all users.
***
## Common patterns
### API route that calls an integration
The AI generates Next.js API routes that call integrations in response to HTTP requests:
> Create an API route that fetches all Slack channels and returns them as JSON.
The AI produces a server-side route that queries the Slack integration and returns the results. The frontend can then call this endpoint to populate a dropdown or display a list.
### Workflow functions
For recurring or event-driven tasks, the AI can wire integrations into [Inngest workflow functions](/workflows/overview):
> Create a workflow that runs every morning and posts a summary of yesterday's Stripe charges to the #finance Slack channel.
The AI generates a scheduled workflow function that:
1. Queries the Stripe integration for yesterday's charges
2. Formats a summary message
3. Posts it to the specified Slack channel
### Chained integration calls
You can combine multiple integrations in a single operation:
> When a new support ticket is created, look up the customer in Salesforce and attach their account details to the ticket.
The AI generates code that calls the Salesforce integration to look up the customer, then writes the enriched data back to the ticket.
***
## Integration availability
For integration code to work in your deployed app, the integration must be:
1. **Connected** at the organization level (not personal visibility)
2. **Active** — the authorization has not expired or been revoked
3. **Accessible** — the integration has the necessary permissions for the actions your code uses
If an integration is disconnected or its authorization expires, API routes and workflows that depend on it will return errors.
If you disconnect an integration that app code depends on, those API routes and workflows will fail until the integration is reconnected. Check for dependent apps before removing a connection.
***
## Debugging integration calls
When an integration call fails in your app code, check the following:
* **Integration status** — Visit the Integrations page and verify the connection is active.
* **Visibility** — Ensure the integration is set to **Organization** visibility, not "You only."
* **Permissions** — Some integrations require specific scopes or permissions. Reauthorize the integration if needed.
* **Sandbox logs** — Check the sandbox console for error messages when testing in the editor.
If you are unsure why an integration call is failing, ask the AI in the chat:
> The Jira integration is returning an error when creating tickets. Can you help me debug it?
The AI can inspect the error, check the integration configuration, and suggest fixes.
# AI Models Reference
Source: https://docs.vybe.build/reference/ai-models
Quick reference for AI model IDs and providers
This is a quick reference for AI model identifiers. For guidance on when to use each model, see [Choosing an AI Model](/building-apps/choosing-a-model).
***
## Model IDs
| Model | ID | Provider |
| ------------------- | ------------------------------- | --------- |
| **Opus 4.5** | `claude-opus-4-5-20251101` | Anthropic |
| **Opus 4.5 - High** | `claude-opus-4-5-20251101-high` | Anthropic |
| **Sonnet 4.5** | `claude-sonnet-4-5-20250929` | Anthropic |
| **Haiku 4.5** | `claude-haiku-4-5-20251001` | Anthropic |
| **GPT-5.1** | `gpt-5.1` | OpenAI |
| **GPT-5.1 - High** | `gpt-5.1-high` | OpenAI |
| **Gemini 3 Pro** | `gemini-3-pro-preview` | Google |
***
## Reasoning levels
| Level | Models |
| ------------ | ----------------------------------- |
| **Standard** | Sonnet 4.5, Haiku 4.5, Gemini 3 Pro |
| **Medium** | Opus 4.5, GPT-5.1 |
| **High** | Opus 4.5 - High, GPT-5.1 - High |
Higher reasoning produces better results for complex tasks but uses more credits.
***
## What's next
* Learn when to use each model: [Choosing an AI Model](/building-apps/choosing-a-model)
* Explore keyboard shortcuts: [Keyboard Shortcuts](/reference/keyboard-shortcuts)
* Read the full glossary: [Glossary](/reference/glossary)
# Glossary
Source: https://docs.vybe.build/reference/glossary
Definitions of key terms and concepts used throughout Vybe
An alphabetical reference of terms you will encounter when using Vybe.
***
| Term | Definition |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent Mode** | The AI's default operating mode where it can create, edit, and delete files, run database queries, install packages, and make changes to your app. |
| **App** | A full-stack Next.js 15 web application built in Vybe. Each app has its own codebase, internal database, and deployment. |
| **App Router** | The routing system used by Next.js 15 (and all Vybe apps). Pages are defined as files in the `src/app/` directory. |
| **Ask Mode** | A read-only AI mode for asking questions and getting explanations about your code without modifying anything. |
| **Client Component** | A React component marked with `"use client"` that runs in the browser. Required for interactivity, event handlers, and React state. |
| **Credit** | The unit of billing in Vybe. AI interactions consume credits based on the model used, reasoning effort, and response length. |
| **Custom API** | Manually configured API credentials stored in Vybe for connecting to services that do not have a built-in integration. |
| **Data Query** | A saved, reusable query against a connected database or integration. Data queries can be shared across apps within an organization. |
| **Deployment** | The process of publishing your app to production, making it accessible at its `.vybe.build` URL for authenticated organization members. |
| **ERD (Entity Relationship Diagram)** | A visual representation of your database schema showing tables, columns, and relationships between them. Available in the Data tab of the editor. |
| **External Database** | A database you own that you have connected to Vybe through the Integrations page. Supports PostgreSQL, MySQL, and Amazon Redshift. |
| **Integration** | A connection to an external service (Slack, Jira, Salesforce, Stripe, etc.) that makes the service's data and actions available in your apps. |
| **Internal Database** | The built-in PostgreSQL database (hosted on Neon) that every Vybe app receives automatically. Managed through Prisma ORM. |
| **Locked File** | A system file that cannot be edited by you or the AI (e.g., `package.json`, `next.config.ts`, `tsconfig.json`). Locked files ensure app infrastructure stability. |
| **Organization** | Your team's workspace in Vybe. All apps, members, integrations, billing, and settings belong to an organization. |
| **Path Access** | Granular access control that restricts specific pages or routes within a deployed app to specific users or roles. |
| **Prisma** | The database ORM used in Vybe apps. Prisma provides a type-safe API for reading and writing data to the internal PostgreSQL database. |
| **Reasoning Effort** | The depth of thinking an AI model applies to a problem. Higher reasoning effort (Medium, High) produces better results for complex tasks but uses more credits. |
| **Recipe** | A pre-configured app starter with specific integrations, guided setup steps, and example database schemas. Recipes help you get started quickly with common use cases. |
| **Sandbox** | The isolated development environment where your app runs during building. Provides live preview with hot reload so you can see changes as the AI writes code. |
| **Server Component** | A React component that renders on the server (the default in Next.js 15). Server Components can access the database, read environment variables, and fetch data directly. |
| **Server Secret** | A unique secret per app (`VYBE_SERVER_SECRET`) used to authenticate server-to-server API calls between Vybe infrastructure and your app. |
| **Shadcn UI** | The component library used in all Vybe apps. Provides 50+ pre-built, accessible UI components including tables, forms, dialogs, and navigation elements. |
| **Template** | A reusable app blueprint created from an existing app. Other members of your organization can use templates to create new apps with the same structure and code. |
| **Thread** | A conversation with the AI about a specific app. Each app can have multiple threads for organizing different features or tasks. |
| **VUT (Vybe User Token)** | A short-lived JWT that authenticates users in deployed Vybe apps. Automatically minted and injected by the platform — you do not need to manage it manually. |
| **Workflow** | A background job or scheduled task powered by Inngest. Used for data syncs, notifications, batch processing, and any operation that should run outside the request/response cycle. |
***
## What's next
* Review the full tech stack: [Tech Stack Reference](/reference/tech-stack)
* Explore AI models: [AI Models Reference](/reference/ai-models)
* Get started building: [Quick Start](/getting-started/quick-start)
# Keyboard Shortcuts
Source: https://docs.vybe.build/reference/keyboard-shortcuts
Quick reference for keyboard shortcuts in the Vybe editor
Keyboard shortcuts help you navigate the Vybe editor faster. Here are the available shortcuts.
***
## Editor shortcuts
| Action | macOS | Windows / Linux |
| --------------------- | --------------- | --------------- |
| Send message | `Cmd + Enter` | `Ctrl + Enter` |
| New line in chat | `Shift + Enter` | `Shift + Enter` |
| Toggle sidebar | `Cmd + B` | `Ctrl + B` |
| Switch to Preview tab | `Cmd + 1` | `Ctrl + 1` |
| Switch to Code tab | `Cmd + 2` | `Ctrl + 2` |
| Switch to Data tab | `Cmd + 3` | `Ctrl + 3` |
| Search files | `Cmd + P` | `Ctrl + P` |
***
## Chat tips
| Action | How |
| ------------------------------ | --------------------------------------------------------------------------------------------- |
| Send a message | Type your prompt and press `Cmd + Enter` (macOS) or `Ctrl + Enter` (Windows/Linux) |
| Add a new line without sending | Press `Shift + Enter` to insert a line break in your message |
| Paste an image | Use `Cmd + V` (macOS) or `Ctrl + V` (Windows/Linux) to paste a screenshot from your clipboard |
***
## Navigation tips
| Action | How |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| Switch between tabs quickly | Use `Cmd/Ctrl + 1/2/3` to jump between Preview, Code, and Data tabs without using the mouse |
| Find a specific file | Press `Cmd/Ctrl + P` to open the file search, then type part of the file name |
| Toggle the sidebar | Press `Cmd/Ctrl + B` to show or hide the sidebar for more screen space |
Keyboard shortcuts may vary depending on your browser and operating system. If a shortcut does not work as expected, check for browser-level shortcut conflicts.
***
## What's next
* Read the full glossary: [Glossary](/reference/glossary)
* Review the tech stack: [Tech Stack Reference](/reference/tech-stack)
* Learn about AI models: [AI Models Reference](/reference/ai-models)
# Tech Stack
Source: https://docs.vybe.build/reference/tech-stack
Complete technology reference for every Vybe app
Every Vybe app is built on the same production-grade technology stack. This page documents every technology, its version, and its role in your app.
***
## Core technologies
| Technology | Version | Purpose | Documentation |
| ---------------- | ------------- | ----------------------------------------- | ---------------------------------------------------- |
| **Next.js** | 15 | React framework with App Router | [nextjs.org/docs](https://nextjs.org/docs) |
| **React** | 19 | UI library for component-based interfaces | [react.dev](https://react.dev) |
| **TypeScript** | 5.5 | Type-safe JavaScript | [typescriptlang.org](https://www.typescriptlang.org) |
| **Tailwind CSS** | 4 | Utility-first CSS framework | [tailwindcss.com](https://tailwindcss.com) |
| **Shadcn UI** | Latest | Component library (50+ components) | [ui.shadcn.com](https://ui.shadcn.com) |
| **Recharts** | Latest | Charting library | [recharts.org](https://recharts.org) |
| **Lucide** | Latest | Icon library | [lucide.dev](https://lucide.dev) |
| **Sonner** | Latest | Toast notifications | [sonner.emilkowal.ski](https://sonner.emilkowal.ski) |
| **PostgreSQL** | Latest (Neon) | Built-in database | [neon.tech/docs](https://neon.tech/docs) |
| **Prisma** | Latest | Database ORM | [prisma.io/docs](https://www.prisma.io/docs) |
| **Inngest** | Latest | Background workflows and scheduled jobs | [inngest.com/docs](https://www.inngest.com/docs) |
***
## Architectural decisions
These are the key architectural patterns used in every Vybe app. Understanding them helps you write better prompts and understand the AI's output.
### App Router (not Pages Router)
Vybe uses the Next.js 15 App Router exclusively. All pages use the `app/` directory structure with file-based routing.
```
src/app/
page.tsx → /
customers/
page.tsx → /customers
[id]/
page.tsx → /customers/:id
api/
customers/
route.ts → /api/customers
```
If you are familiar with Next.js Pages Router (`pages/` directory), note that Vybe does not use it. All routing, layouts, and data fetching follow App Router conventions.
### Server Components by default
Components are server-rendered unless explicitly marked with `"use client"` at the top of the file. Server Components can fetch data directly, access the database, and read environment variables.
```tsx theme={null}
// This is a Server Component (default)
export default async function CustomersPage() {
const customers = await prisma.customer.findMany()
return
}
```
```tsx theme={null}
"use client"
// This is a Client Component (explicitly opted in)
export default function SearchBar() {
const [query, setQuery] = useState('')
// Client-side interactivity...
}
```
Use Client Components only when you need browser APIs, event handlers, or React state.
### API routes instead of Server Actions
Vybe apps use API routes for all server-side mutations. Server Actions are not used.
```tsx theme={null}
// src/app/api/customers/route.ts
import { NextResponse } from 'next/server'
export async function GET(request: Request) {
const customers = await prisma.customer.findMany()
return NextResponse.json(customers)
}
export async function POST(request: Request) {
const data = await request.json()
const customer = await prisma.customer.create({ data })
return NextResponse.json(customer, { status: 201 })
}
```
### Dynamic route params in Next.js 15
Next.js 15 changed how dynamic route parameters work. The `params` object is now a Promise:
```tsx theme={null}
// src/app/customers/[id]/page.tsx
export default async function CustomerPage({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
const customer = await prisma.customer.findUnique({ where: { id } })
// ...
}
```
This `Promise<{ id: string }>` pattern is specific to Next.js 15 and the App Router. The AI handles this automatically, but it is useful to understand if you are reading the generated code.
***
## Database
Every Vybe app includes a built-in PostgreSQL database hosted on Neon. The database is managed through Prisma ORM.
**Key details:**
* Schema is defined in `prisma/schema.prisma`
* Migrations are managed by the AI when you request schema changes
* The database is available in both development (sandbox) and production (deployed app)
* You can also connect external databases (PostgreSQL, MySQL, Amazon Redshift) through Integrations
For more on databases, see [App Data](/data/app-data) and [External Data](/data/external-data).
***
## Background workflows
Inngest powers background processing in Vybe apps. Use workflows for:
* **Scheduled tasks** — sync data every 15 minutes, send daily reports
* **Event-driven processing** — trigger actions when database records change
* **Long-running operations** — batch data processing, multi-step pipelines
Workflows run outside of the request/response cycle, so they are not subject to API route timeouts.
For more on workflows, see [Workflows Overview](/workflows/overview).
***
## What this means for your prompts
You do not need to specify technology choices in your prompts. The AI knows the full stack and uses the right tools automatically. However, understanding the stack helps you:
* **Read the generated code** more easily
* **Ask targeted questions** about how things work
* **Debug issues** by understanding the architecture
* **Write better prompts** by referencing the right concepts (e.g., "add an API route" instead of "add a server action")
***
## What's next
* See which AI models are available: [AI Models Reference](/reference/ai-models)
* Review available packages: [Available Packages](/tips/available-packages)
* Understand platform constraints: [Platform Limitations](/tips/platform-limitations)
# Security Overview
Source: https://docs.vybe.build/security/overview
Enterprise-grade security for your internal applications and data
Every Vybe application is protected by default — behind authentication, encrypted in transit and at rest, and isolated from other workspaces. Security is built into every layer of the platform, not bolted on after the fact.
Vybe is **SOC 2 Type II certified** and undergoes regular third-party penetration testing.
For comprehensive details on our security architecture, compliance certifications, and security practices, visit our [Security page](https://www.vybe.build/security).
***
## What's next
* Understand how secrets are stored and managed: [Secrets & Encryption](/security/secrets-and-encryption)
* Learn about access control: [App Access Levels](/teams/app-access)
* Learn about authentication in deployed apps: [App Authentication](/teams/app-authentication)
# Secrets & Encryption
Source: https://docs.vybe.build/security/secrets-and-encryption
How Vybe stores, encrypts, and manages your API keys, database credentials, and sensitive configuration
Your apps depend on sensitive credentials — API keys, database connection strings, OAuth tokens, and more. Vybe encrypts all of these at rest and provides a secure pipeline for injecting them into your app at deployment time, so secrets never appear in your code or version history.
***
## Encryption at rest
All sensitive values are encrypted using **AES-256-GCM** before they are stored in the database. This is an additional encryption layer on top of the base database encryption provided by Neon.
| Secret type | Examples |
| ------------------------------- | ----------------------------------------------------- |
| **Custom API credentials** | API keys, Bearer tokens, basic auth passwords |
| **Database connection strings** | PostgreSQL URLs, MySQL URLs, Redshift URLs |
| **SSH private keys** | Keys used for tunneled database connections |
| **OAuth tokens** | Access and refresh tokens from connected integrations |
Once a secret is saved, it is stored only in its encrypted form. The plaintext value is never persisted to disk or logged.
***
## Encryption in transit
All connections between your browser, Vybe services, and your deployed apps are encrypted using TLS/HTTPS:
* **Dashboard and editor** — All interactions with the Vybe platform
* **Deployed apps** — All traffic to `*.vybe.build` URLs
* **API calls** — Communication between your app and Vybe services
* **Integration connections** — OAuth flows and API calls to third-party services
* **Database connections** — Encrypted by default; SSH tunneling available for additional security
Cookies use `HttpOnly`, `Secure`, and `SameSite` attributes. Cross-subdomain communication is protected with security headers.
***
## Database encryption
### Internal databases
Every organization receives an isolated Neon PostgreSQL project with:
* **Encryption at rest** — Neon encrypts all stored data at the infrastructure level
* **Automatic backups** — 7-day retention with point-in-time restore to millisecond precision
* **Project isolation** — Complete data separation between organizations
The `DATABASE_URL` connection string for your app's internal database is generated, encrypted, and injected automatically. You never need to configure it manually.
### External databases
When you connect an external database (PostgreSQL, MySQL, Redshift), the connection credentials are encrypted with AES-256-GCM before storage:
* **Connection URLs** — The full connection string including host, port, database, username, and password
* **SSH private keys** — Keys used for tunneled connections to databases behind firewalls
At runtime, the decrypted connection string is used to execute queries and is never exposed in your app's code.
All external database queries are routed through Vybe's security middleware, which enforces:
* **Parameterized queries** — Prevents SQL injection attacks
* **Request validation** — Sanitizes and validates all query parameters
* **Read-only enforcement** — Optional mode that prevents accidental writes to production databases
***
## Masked after creation
After you save a secret — whether it is a Custom API credential, a database URL, or an SSH key — it is masked in the UI and cannot be viewed again. You will see a placeholder like `••••••••` instead of the actual value.
If you need to change a secret, you replace it entirely with a new value. There is no way to retrieve the original.
Never hardcode secrets in your app's source code. Hardcoded secrets in code are visible in the version history and to anyone with edit access to the app.
***
## Integration credentials
OAuth tokens and API keys for connected services (like Slack, Salesforce, or HubSpot) are managed through Vybe's integration platform with multiple layers of protection:
* **Encrypted storage** — Tokens are encrypted with AES-256-GCM before being stored
* **No client-side exposure** — Auth tokens are never sent to the browser or exposed in client-side code
* **Automatic token refresh** — OAuth tokens are refreshed automatically before they expire, with no intervention required
* **Secure provider** — Credentials are managed through a dedicated secure integration provider
* **No direct access** — Your app accesses integration data through Vybe's APIs, which handle authentication on your behalf
***
## Custom API credentials
When you create a Custom API in the Integrations page, the credentials you provide are encrypted and stored securely:
Navigate to **Integrations** > **Custom APIs** and click **Create Custom API**.
Provide the API name, authentication type, and credentials (API key, token, etc.).
Once saved, the credentials are encrypted immediately. They appear masked in the UI and cannot be retrieved.
When the AI builds an app that uses this Custom API, the credentials are injected securely at runtime. You reference them through the integration system, not by copying the values into your code.
***
## Best practices
When connecting external production databases, enable read-only mode to prevent accidental writes. This is especially important for databases shared across your organization.
If you suspect a credential has been compromised, replace it immediately from the Integrations page. The old value is discarded and the new value is encrypted and deployed on your next deploy.
Set Custom API credentials to "You only" visibility unless the entire team needs access. This limits the blast radius if a credential is misused.
For databases behind firewalls or containing particularly sensitive data, use SSH tunneling to add an extra layer of security beyond TLS encryption.
***
## What's next
* Review the overall security architecture: [Security Overview](/security/overview)
* Learn about authentication in deployed apps: [App Authentication](/teams/app-authentication)
# App Access Levels
Source: https://docs.vybe.build/teams/app-access
Control who can see and use each app with organization, restricted, and user-level access
Not every app needs to be visible to everyone in your organization. Vybe gives you three levels of app access so you can control exactly who sees what — from shared team tools to personal works in progress.
***
## Access levels
| Level | Who Can Access | Use Case |
| -------------------------- | --------------------------------------- | ------------------------------------------------------------- |
| **Organization** (default) | All members of your organization | Shared team tools, company dashboards, org-wide utilities |
| **Restricted** | Only specific users you grant access to | Sensitive tools, department-specific apps, HR or finance apps |
| **User** | Only the app creator | Personal tools, prototypes, works in progress |
When you create a new app, it defaults to **Organization** access. All members of your workspace can see and use it based on their role.
***
## Setting the access level
Navigate to your app and open the **Settings** tab.
Scroll to the **Access** section in the settings panel.
Select **Organization**, **Restricted**, or **User** from the dropdown.
The change takes effect immediately. Members who no longer have access will see the app removed from their dashboard.
***
## Organization access
This is the default. Every member of your organization can access the app. What they can do depends on their role:
* **Owners, Admins, and Editors** can view the deployed app and edit it via the AI chat.
* **Members** can view and use the deployed app but cannot edit it.
Use Organization access for shared tools that your entire team needs — dashboards, trackers, internal utilities.
***
## Restricted access
Restricted access lets you share an app with specific people. Only users you explicitly grant access to can see or use the app.
### Granting access to users
After setting the access level to **Restricted**:
1. Open the **Access** section in app settings.
2. Click **Add User**.
3. Search for the team member by name or email.
4. Select their access role:
| Access Role | What they can do |
| ----------- | ------------------------------------------------------- |
| **Viewer** | Can access and use the deployed app |
| **Editor** | Can access the deployed app and edit it via the AI chat |
5. Click **Add** to grant access.
You can add as many users as you need. Each user's access role is independent — you can have some users as Viewers and others as Editors on the same app.
Use Restricted access for sensitive apps like HR tools, finance dashboards, or admin panels that only specific team members should see.
***
## User access
User access makes the app visible only to you — the person who created it. No other member of your organization can see or access it.
This is ideal for:
* **Personal tools** you are building for your own use
* **Works in progress** that are not ready to share
* **Prototypes** you want to test before opening up to the team
When you are ready to share, change the access level to Organization or Restricted.
***
## Path-level access
Beyond controlling who can access an entire app, you can restrict specific pages or routes within an app to specific users. This lets you build a single app with different sections for different audiences.
### How it works
1. Open your app's **Settings** tab.
2. Navigate to the **Path Access** section.
3. Click **Add Path Rule**.
4. Enter the path you want to restrict (for example, `/admin`).
5. Select which users can access that path.
### Example
Suppose you have a team management app where most pages are accessible to everyone, but the `/admin` page should only be available to team leads:
| Path | Accessible to |
| ------------ | --------------- |
| `/` | All app users |
| `/dashboard` | All app users |
| `/admin` | Team leads only |
Users who do not have access to a restricted path will receive an access denied response when they try to navigate to it.
Path-level access works on top of the app's access level. A user must first have access to the app itself (via Organization, Restricted, or User access) before path-level rules apply.
***
## Creator access
The app creator always has full access to their app, regardless of the access level setting. Even if you set an app to Restricted and do not add yourself to the access list, you can still view and edit the app.
***
## What is next
* Understand how user authentication works in deployed apps: [App Authentication](/teams/app-authentication)
* Learn about member roles and what each can do: [Members & Roles](/teams/members-and-roles)
* Share resources across your team: [Sharing & Collaboration](/teams/sharing-and-collaboration)
# Authentication in Deployed Apps
Source: https://docs.vybe.build/teams/app-authentication
How Vybe authenticates users and injects identity context into your deployed apps
Every deployed Vybe app is protected by authentication. There are no public URLs — users must be authenticated members of your organization with appropriate access rights before they can reach your app.
This page explains how the authentication flow works and how you can use the current user's identity in your app code.
***
## The authentication flow
When someone visits a deployed app, Vybe handles authentication automatically:
The user navigates to your deployed app at `-.vybe.build`.
The Vybe middleware checks whether the user has an active session (a valid authentication cookie).
If the user is not authenticated, they are redirected to the Vybe login page. After signing in, they are sent back to the original app URL.
Once authenticated, Vybe verifies that the user has access to this specific app based on the app's [access level](/teams/app-access) and any user-level grants.
If the user passes the access check, Vybe mints a short-lived Vybe User Token (VUT) and injects it — along with user identity headers — into the request before forwarding it to your app.
Your app receives the request with the user's identity context available in the request headers.
***
## Identifying the current user
When a request reaches your app, the current user's email is available in the request headers. You can use this to personalize the app experience, filter data, or implement user-specific logic.
### In an API route
```typescript theme={null}
// app/api/my-tasks/route.ts
import { sql } from '@/lib/db';
export async function GET(request: Request) {
const userEmail = request.headers.get('x-vybe-user-email');
const tasks = await sql`
SELECT * FROM tasks WHERE assignee_email = ${userEmail}
`;
return Response.json(tasks);
}
```
### In a server component
```typescript theme={null}
// app/dashboard/page.tsx
import { headers } from 'next/headers';
import { sql } from '@/lib/db';
export default async function DashboardPage() {
const headersList = await headers();
const userEmail = headersList.get('x-vybe-user-email');
const myProjects = await sql`
SELECT * FROM projects WHERE owner_email = ${userEmail}
`;
return (
My Projects
{myProjects.map((project) => (
{project.name}
))}
);
}
```
You do not need to build your own login page or session management. Vybe handles all of that for you. Just read the user identity from the request headers.
***
## Two-factor request authentication
When your app makes API calls to Vybe services (for example, to access integration data or run data queries), the request is authenticated with two credentials:
| Credential | Purpose | How it is provided |
| ----------------------------- | ------------------- | --------------------------------------------------- |
| **`VYBE_SERVER_SECRET`** | Identifies the app | Injected as an environment variable at deployment |
| **`x-vybe-user-token`** (VUT) | Identifies the user | Injected as a request header by the Vybe middleware |
* **App-level resources** (like shared integration connections) require only the server secret.
* **User-level resources** (like a user's personal integration account) require both the server secret and the VUT.
This two-factor approach ensures that API calls are both app-authorized and user-authorized.
***
## How this differs from traditional auth
In a traditional web app, you would build a login page, manage sessions, store user credentials, and handle password resets. In Vybe, all of this is handled by the platform:
| Concern | Traditional App | Vybe App |
| ------------------ | -------------------------------- | ----------------------------------------------------- |
| Login page | You build it | Vybe provides it |
| Session management | You implement it | Vybe handles it |
| User identity | You query your database | You read request headers |
| Access control | You implement middleware | Vybe enforces it before your app receives the request |
| Token management | You generate and validate tokens | Vybe mints and validates the VUT automatically |
Apps cannot be accessed publicly. All users must be authenticated members of your organization with appropriate access rights. There is no way to make a Vybe app publicly accessible.
***
## Common patterns
### Personal dashboard
Build an app where each user sees only their own data:
```typescript theme={null}
export async function GET(request: Request) {
const userEmail = request.headers.get('x-vybe-user-email');
const myMetrics = await sql`
SELECT * FROM metrics WHERE user_email = ${userEmail}
`;
return Response.json(myMetrics);
}
```
### Role-based content
Combine user identity with your own role data to show different content:
```typescript theme={null}
export async function GET(request: Request) {
const userEmail = request.headers.get('x-vybe-user-email');
const user = await sql`
SELECT role FROM app_users WHERE email = ${userEmail}
`;
if (user[0]?.role === 'manager') {
const teamData = await sql`SELECT * FROM team_metrics`;
return Response.json(teamData);
}
const personalData = await sql`
SELECT * FROM metrics WHERE user_email = ${userEmail}
`;
return Response.json(personalData);
}
```
***
## What is next
* Learn about secrets and encryption: [Secrets & Encryption](/security/secrets-and-encryption)
* Control who can access your apps: [App Access Levels](/teams/app-access)
# Members & Roles
Source: https://docs.vybe.build/teams/members-and-roles
Invite team members and control what they can do with role-based permissions
Every member of your organization is assigned a role that determines what they can do. Roles control access to apps, members management, and billing — so you can give your team the right level of access without overexposing sensitive settings.
***
## Role levels
Vybe has four role levels, from most to least permissive:
| Role | Apps | Members & Billing | Description |
| ---------- | ---------------------------- | ----------------- | ----------------------------------------------------- |
| **Owner** | Create, edit, deploy, delete | Full access | Full control; can delete the organization |
| **Admin** | Create, edit, deploy, delete | Full access | Same as Owner, except cannot delete the organization |
| **Editor** | Create, edit, deploy, delete | No access | Can build apps, but cannot manage members or billing |
| **Member** | View only | No access | Can use deployed apps, but cannot create or edit them |
Every organization must have at least one Owner. The Owner role identifies the original creator and is the only role that can delete the organization.
***
## Inviting members
Navigate to **Settings** in the sidebar, then select **Members**.
Click the **Invite Member** button at the top of the members list.
Provide the person's email address and select the role you want to assign. You can invite multiple people at once.
Click **Send Invite**. The invitee receives an email with a link to join your organization.
Invitations expire after 14 days. If someone has not accepted their invitation, you can resend it from the Members page.
***
## Changing a member's role
Owners and Admins can change the role of any member in the organization.
1. Go to **Settings** > **Members**.
2. Find the member whose role you want to change.
3. Click the role dropdown next to their name.
4. Select the new role.
The change takes effect immediately. The member's permissions update the next time they load a page.
***
## Removing members
To remove someone from your organization:
1. Go to **Settings** > **Members**.
2. Find the member you want to remove.
3. Click the options menu and select **Remove**.
Removing a member revokes their access to all apps, integrations, and data in the organization. Apps they created remain in the organization and are still accessible to other members with the appropriate role.
Removing a member does not delete their Vybe account — it only removes them from your organization. They can still access other organizations they belong to.
***
## Seat types on paid plans
Paid plans distinguish between two types of seats, based on the member's role:
| Seat Type | Roles | What they can do |
| ----------- | -------------------- | ------------------------------------------------------------------------ |
| **Builder** | Owner, Admin, Editor | Create and edit apps using the AI chat, manage integrations, deploy apps |
| **Viewer** | Member | Access deployed apps, view app details, use apps your team has built |
Builder seats are typically more expensive than Viewer seats because they include access to the AI agent and app editing capabilities. Viewer seats are for team members who only need to use the finished apps.
Check your plan details on the **Billing** page to see how many Builder and Viewer seats are included and the cost of additional seats.
***
## What is next
* Control who can access specific apps: [App Access Levels](/teams/app-access)
* Understand how authentication works in deployed apps: [App Authentication](/teams/app-authentication)
* Learn about organizations: [Organizations](/teams/organizations)
# Organizations
Source: https://docs.vybe.build/teams/organizations
Your team workspace in Vybe — where apps, members, integrations, and billing come together
An organization is your team's workspace in Vybe. Everything you build — apps, integrations, data connections, and members — belongs to an organization. It is the top-level container for all your work.
***
## What belongs to an organization
Each organization is a self-contained workspace with its own:
| Resource | Description |
| ---------------- | -------------------------------------------------------- |
| **Apps** | All apps created by members of the organization |
| **Members** | The people who can access and build within the workspace |
| **Integrations** | Connected services, databases, and custom APIs |
| **Billing** | Subscription plan, credit balance, and payment settings |
| **Slug** | A unique identifier used in deployed app URLs |
Your deployed app URLs follow the pattern `-.vybe.build`. For example, if your organization slug is `acme` and you deploy an app called `expense-tracker`, the URL will be `expense-tracker-acme.vybe.build`.
***
## Creating an organization
You get your first organization automatically when you sign up for Vybe. If you need additional workspaces — for example, to separate departments or clients — you can create more.
Click your organization name in the top-left corner of the sidebar.
Select **Create Organization** from the dropdown menu.
Enter a name and slug for your new organization. The slug must be unique and will be used in all deployed app URLs.
Use separate organizations when you need completely isolated workspaces — different billing, different members, different integrations. For teams that share resources, a single organization with role-based access is usually simpler.
***
## Switching between organizations
If you belong to multiple organizations, you can switch between them at any time.
1. Click your organization name in the top-left corner of the sidebar.
2. Select the organization you want to switch to.
Your apps, integrations, and member list update immediately to reflect the selected workspace. Each organization is fully independent — apps and data in one organization are not visible from another.
***
## Organization settings
Manage your organization from the **Settings** page in the sidebar. From here you can:
* **General** — Update the organization name and slug
* **Members** — Invite, manage, and remove team members
* **Billing** — View your plan, credit balance, and manage your subscription
* **Integrations** — Review and manage connected services
Changing your organization slug will update all deployed app URLs. Existing links will stop working. Coordinate with your team before making this change.
***
## Deleting an organization
If you no longer need a workspace, you can delete the organization from **Manage Organizations** > **Organization**. This permanently removes all apps, data, integrations, and member associations.
Deleting an organization cannot be undone. All apps, databases, and deployment URLs associated with the organization will be permanently removed.
***
## What is next
* Learn about member roles and permissions: [Members & Roles](/teams/members-and-roles)
* Control who can access specific apps: [App Access Levels](/teams/app-access)
* Share resources across your team: [Sharing & Collaboration](/teams/sharing-and-collaboration)
# Sharing & Collaboration
Source: https://docs.vybe.build/teams/sharing-and-collaboration
Work together on apps, share integrations, reuse queries, and streamline your team workflow
Vybe is built for teams. Beyond role-based access and app-level permissions, there are several features designed to help your team work together efficiently — from shared integrations to reusable templates.
***
## Shared integrations
When you connect an integration (like Slack, Salesforce, or a database), you can set its visibility to **Organization** so every member of your workspace can use it in their apps.
| Visibility | Who can use it | Best for |
| ---------------- | -------------------------------- | ------------------------------------------- |
| **Organization** | All workspace members | Shared team accounts, company-wide services |
| **You only** | Only the person who connected it | Personal accounts, sensitive credentials |
Connect a service once and use it across every app in your organization. There is no need to re-authenticate or reconfigure credentials for each app.
Set shared team accounts (like your company's Salesforce or Jira) to Organization visibility. Keep personal accounts (like your individual Gmail) set to You only.
***
## Shared data queries
Data queries let you save SQL queries and API queries that can be reused across your organization. Write a query once, name it, and any team member can reference it in their apps.
This is especially useful for:
* **Complex joins** that multiple apps need
* **Standard reports** your team runs regularly
* **Curated datasets** that should be consistent across tools
To create a shared query:
1. Navigate to **Integrations** > **Data Queries**.
2. Click **Create Data Query**.
3. Select the data source, write your query, and give it a descriptive name.
4. Save — it is now available to all members of your organization.
***
## Favoriting apps
As your organization builds more apps, it helps to have quick access to the ones you use most. Click the star icon on any app to add it to your favorites.
Favorited apps appear in a dedicated section at the top of your dashboard, so you can launch them without scrolling through your full app list.
***
## Recent apps
Your dashboard automatically shows recently accessed apps. This gives you a quick way to jump back into whatever you were working on last — whether it is an app you are building or one you are using.
***
## Templates
Templates are pre-built app blueprints created by the Vybe team and community. Browse available templates when creating a new app to start from a proven design instead of building from scratch.
1. Click **New App** from your dashboard.
2. Navigate to the **Templates** view.
3. Browse available templates and select one.
4. Vybe creates a new app with the template's codebase and structure. You can then customize it for your specific needs.
See [Templates](/building-apps/templates) for more details.
***
## App access sharing
For apps that should only be visible to specific people, use [Restricted access](/teams/app-access) to share with individual team members. You can grant each person either Viewer or Editor access, giving you fine-grained control over who sees what.
This is useful for:
* **Department-specific tools** — share an HR app only with the HR team
* **Manager dashboards** — share a reporting app with team leads
* **Staged rollouts** — share with a small group before opening to the full organization
***
## Single Sign-On (SSO)
SSO is planned for Enterprise plans. Contact the Vybe team at [team@vybe.build](mailto:team@vybe.build) to learn more.
***
## Collaboration summary
Here is a quick overview of how different sharing features map to common team scenarios:
Connect a service once, use it across all apps. Set visibility to Organization for team-wide access.
Save and name reusable queries. Any team member can reference them in their apps.
Start from pre-built app blueprints. Clone and customize for your needs.
Share specific apps with specific people. Grant Viewer or Editor access per user.
***
## What is next
* Control who can access your apps: [App Access Levels](/teams/app-access)
* Understand member roles: [Members & Roles](/teams/members-and-roles)
* Learn about your organization workspace: [Organizations](/teams/organizations)
# Available Packages
Source: https://docs.vybe.build/tips/available-packages
Pre-approved npm packages and built-in libraries available in every Vybe app
Every Vybe app comes with a curated set of libraries pre-installed. In addition, a selection of pre-approved packages can be installed by the AI on request. This page covers everything that is available.
***
## Pre-installed packages
These packages are included in every Vybe app automatically. You do not need to install them — they are ready to use.
| Package | Version | Description |
| ---------------- | ------- | ------------------------------------------------------------------ |
| **Next.js** | 15 | React framework with App Router, server components, and API routes |
| **React** | 19 | UI library for building component-based interfaces |
| **TypeScript** | 5.5 | Type-safe JavaScript with full IDE support |
| **Tailwind CSS** | 4 | Utility-first CSS framework for rapid styling |
| **Shadcn UI** | Latest | Component library with 50+ accessible, production-grade components |
| **Recharts** | Latest | Charting library for bar, line, area, and pie charts |
| **Lucide React** | Latest | Icon library with thousands of SVG icons |
| **Sonner** | Latest | Toast notification library for success, error, and info messages |
| **Prisma** | Latest | Database ORM for the built-in PostgreSQL database |
These form the core of every Vybe app. The AI uses them automatically when building your interfaces, charts, database queries, and notifications.
***
## Additional pre-approved packages
These packages can be installed by the AI when you need them. Ask the AI to add them to your project, or describe a feature that requires them and the AI will install the package as part of building it.
Rich text editor framework. Build full-featured text editors with formatting toolbars, mentions, links, images, and collaborative editing capabilities.
**Use it for:** Content management, note-taking, document editing, rich form fields.
> Add a rich text editor for writing blog posts with bold, italic, headings, links, and bullet lists.
Library for building interactive node-based diagrams, flowcharts, org charts, and graph visualizations with drag-and-drop support.
**Use it for:** Workflow builders, org charts, process diagrams, pipeline visualizations.
> Create a workflow builder where users can add steps, connect them with arrows, and configure each step.
***
## What comes with Shadcn UI
Shadcn UI deserves special mention because it provides the majority of UI components used in Vybe apps. Here is what is included:
**Layout:** Card, Separator, Sheet, Dialog, Drawer, Tabs, Accordion, Collapsible, ScrollArea, AspectRatio, Resizable
**Forms:** Input, Textarea, Select, Checkbox, RadioGroup, Switch, Slider, DatePicker, ComboBox, Form, Label
**Data Display:** Table, DataTable, Badge, Avatar, Progress, Calendar, HoverCard
**Feedback:** Alert, AlertDialog, Toast (via Sonner), Skeleton
**Navigation:** Breadcrumb, NavigationMenu, Sidebar, Menubar, Pagination, Command
**Overlays:** Dialog, Popover, Tooltip, DropdownMenu, ContextMenu
You do not need to install or import these separately. The AI uses them automatically based on your prompts. For the full component catalog, visit [ui.shadcn.com](https://ui.shadcn.com).
***
## Can I use other packages?
The package list is curated for security, compatibility, and stability. There are a few things to keep in mind:
**Why packages are restricted:**
* Every package is tested for compatibility with the Vybe runtime and Next.js 15
* Security review prevents supply chain risks
* Consistent dependencies across apps make debugging easier
**If you need a package that is not listed:**
* Contact the Vybe team at [team@vybe.build](mailto:team@vybe.build) to request it
* Include the package name, what you need it for, and a link to the npm page
* The team reviews requests and adds approved packages to the list
**In the meantime:**
* The AI can often implement similar functionality using existing packages
* For example, instead of a specialized date library, the AI can use native JavaScript `Date` with Shadcn's DatePicker
* For custom visualizations beyond Recharts, the AI can build SVG-based components with Tailwind
Before requesting a new package, describe what you are trying to build to the AI. It may already have a way to accomplish it with the existing tools.
***
## What's next
* Learn what UI components are available: [Building Effective UIs](/tips/building-uis)
* Understand platform constraints: [Platform Limitations](/tips/platform-limitations)
* Review the full tech stack: [Tech Stack Reference](/reference/tech-stack)
# Building Effective UIs
Source: https://docs.vybe.build/tips/building-uis
UI components, patterns, and design tips for building polished internal tools
Every Vybe app comes with a complete UI toolkit pre-installed. You do not need to install anything or configure component libraries — just describe what you want and the AI builds it using the right components automatically.
This page covers what is available and how to get the most out of it.
***
## Shadcn UI components
Vybe includes over 50 pre-installed Shadcn UI components. These are production-grade, accessible components that the AI uses to build your interfaces.
### Layout
| Component | Use case |
| --------------- | ------------------------------------------------------- |
| **Card** | Container for related content — summaries, stats, forms |
| **Separator** | Visual divider between sections |
| **Sheet** | Slide-out panel from the edge of the screen |
| **Dialog** | Modal window for focused interactions |
| **Drawer** | Bottom sheet for mobile-style interactions |
| **Tabs** | Switch between related content sections |
| **Accordion** | Expandable/collapsible content sections |
| **Collapsible** | Toggle visibility of content blocks |
### Forms
| Component | Use case |
| -------------- | ------------------------------------- |
| **Input** | Single-line text entry |
| **Textarea** | Multi-line text entry |
| **Select** | Dropdown selection from a list |
| **Checkbox** | Toggle on/off for boolean options |
| **RadioGroup** | Select one option from a group |
| **Switch** | Toggle switch for on/off states |
| **DatePicker** | Calendar-based date selection |
| **ComboBox** | Searchable dropdown with autocomplete |
### Data display
| Component | Use case |
| ------------- | ----------------------------------------------------------- |
| **Table** | Basic table for structured data |
| **DataTable** | Full-featured table with sorting, filtering, and pagination |
| **Badge** | Small label for status, category, or count |
| **Avatar** | User or entity profile image |
| **Progress** | Progress bar for completion tracking |
### Feedback and overlays
| Component | Use case |
| ------------------ | ---------------------------------------------- |
| **Alert** | Inline message for important information |
| **Toast (Sonner)** | Temporary notification popup |
| **AlertDialog** | Confirmation dialog before destructive actions |
| **Popover** | Floating content attached to a trigger |
| **Tooltip** | Hover text for additional context |
| **DropdownMenu** | Context menu or action menu |
### Navigation
| Component | Use case |
| ------------------ | --------------------------------------- |
| **Breadcrumb** | Show page hierarchy and navigation path |
| **NavigationMenu** | Top-level navigation links |
| **Sidebar** | Vertical navigation for multi-page apps |
You do not need to memorize component names. Just describe what you want in your prompt — "add a confirmation popup before deleting" — and the AI will choose the right component (AlertDialog in this case).
***
## Charts
Vybe uses Recharts with Shadcn chart wrappers for data visualization. The AI can generate charts from your data with a simple prompt.
**Available chart types:**
* Bar charts (vertical and horizontal)
* Line charts
* Area charts
* Pie charts and donut charts
**Example prompts:**
> Add a line chart showing monthly revenue trends for the past 12 months.
> Create a pie chart showing the distribution of support tickets by status.
> Add a bar chart comparing sales by region. Use horizontal bars and sort by value.
The AI automatically configures chart tooltips, legends, and responsive sizing using the Shadcn chart components:
```tsx theme={null}
} />
```
Charts pull data from your database or integrations at render time. For large datasets, consider adding date range filters to limit the query scope and improve performance.
***
## Icons
Thousands of icons are available through the Lucide icon library. The AI selects appropriate icons automatically, but you can request specific ones:
> Use a bar chart icon next to the Analytics heading and a settings gear icon in the sidebar.
Icons are imported from `lucide-react`:
```tsx theme={null}
import { Users, Settings, BarChart, Search, Plus, Trash2 } from 'lucide-react'
```
Browse the full icon catalog at [lucide.dev/icons](https://lucide.dev/icons).
***
## Toast notifications
Vybe uses Sonner for toast notifications — the small popups that confirm actions or report errors.
```tsx theme={null}
import { toast } from 'sonner'
toast.success('Customer saved successfully')
toast.error('Failed to delete record')
toast.info('Syncing data from Salesforce...')
```
The AI adds toasts automatically when building forms, delete actions, and API calls. You can also request them explicitly:
> Show a success toast when the form is submitted and an error toast if the API call fails.
***
## Tailwind CSS
All styling in Vybe uses Tailwind CSS utility classes. This gives you precise control over layout, spacing, colors, typography, and responsive behavior.
The AI writes Tailwind classes automatically, but you can guide it with design preferences:
> Use a two-column grid layout with a gap of 16px. Make the cards have rounded corners and a subtle shadow.
> Add responsive breakpoints — single column on mobile, two columns on tablet, three columns on desktop.
Tailwind includes built-in dark mode support, responsive utilities, and a comprehensive design system.
***
## Design tips for internal tools
Internal tools have different priorities than consumer apps. Here are patterns that work well:
### Use data tables as the backbone
Most internal tools revolve around lists of data. The DataTable component handles sorting, filtering, pagination, and row selection out of the box.
> Show customers in a data table with sortable columns, a search bar, and pagination. Add a dropdown filter for account status.
### Add search and filters to every list
Your users will always need to find specific records. Make it easy:
> Add a search bar that filters by name or email. Add dropdown filters for status and date range.
### Use Cards for summary sections
Cards work well for KPI dashboards, overview panels, and summary statistics at the top of a page.
> Add four summary cards at the top: Total Customers, Active Subscriptions, Monthly Revenue, and Churn Rate.
### Use Tabs to organize related content
When a page has multiple related views, Tabs keep things clean without requiring separate pages.
> Organize the customer detail page with tabs for Overview, Orders, Support Tickets, and Activity Log.
### Keep navigation simple
Internal tools should be easy to navigate. Use a sidebar for multi-page apps and top navigation for simpler apps.
> Add a sidebar with links to Dashboard, Customers, Orders, and Settings. Highlight the active page.
### Be consistent with spacing and typography
The AI follows consistent spacing patterns by default. If you want to adjust the density:
> Make the layout more compact — reduce padding and use smaller text for the table.
> Give the dashboard more breathing room — increase spacing between cards and sections.
***
## Common UI patterns
Here are prompts for building the most common internal tool interfaces:
**Master-detail layout:**
> Build a two-panel layout. The left panel shows a list of orders. Clicking an order shows its details in the right panel.
**Settings page:**
> Create a settings page with sections for Profile, Notifications, and Integrations. Use a vertical tab layout on the left.
**Search and filter page:**
> Build a search page with a search bar, category filters, date range selector, and a results table below.
**Form with validation:**
> Create a form to add a new customer with fields for name (required), email (required, must be valid), phone, and company. Show validation errors inline.
**Empty states:**
> When there are no results, show a friendly empty state with an icon and a message explaining what to do.
***
## What's next
* Write better prompts for the AI: [Prompting Best Practices](/tips/prompting)
* Understand platform constraints: [Platform Limitations](/tips/platform-limitations)
* See what packages are available: [Available Packages](/tips/available-packages)
# Platform Limitations
Source: https://docs.vybe.build/tips/platform-limitations
What Vybe can and cannot do — hard limits, workarounds, and best practices
Vybe is built for internal tools. That focus means some capabilities are intentionally outside the platform's scope, while others have practical workarounds. This page is a transparent reference so you can plan your apps accordingly.
***
## Hard limitations
These are constraints with no workaround within the platform.
| Limitation | Details |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **No public apps** | Apps are for authenticated organization members only. You cannot build public-facing websites or apps with public sign-up. |
| **No multi-tenant auth** | There is no public user registration or multi-tenant authentication system. All users must be members of your Vybe organization. |
| **No arbitrary npm packages** | Only pre-approved packages can be installed. You cannot add packages from the npm registry freely. See [Available Packages](/tips/available-packages) for the full list. |
| **No terminal access** | Neither you nor the AI have terminal or CLI access. All operations happen through the Vybe interface. |
| **No SSE or WebSockets** | Server-Sent Events and WebSocket connections are not supported. Long-lived connections cannot be established. |
| **No background processes** | You cannot run long-running background tasks directly. Use Inngest workflows for scheduled or asynchronous processing. |
***
## Limitations with workarounds
These constraints have practical alternatives you can use.
| Limitation | Workaround |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No webhooks** | Use polling via Inngest scheduled workflows to check for updates from external services at regular intervals. |
| **No file uploads to local storage** | Process files in memory (CSV parsing, data extraction), store results in the database, or use an external storage service through a Custom API integration. |
| **No user directory** | Create a `users` table in your internal database and match records by email from the authenticated session. |
| **No integration discovery** | If a service is not in the integration catalog, use Custom APIs with direct REST access. Any service with an API can be connected this way. |
***
## Working within the limits
These patterns help you build effective apps within Vybe's constraints.
### Polling instead of real-time updates
Since SSE and WebSockets are not available, use a polling pattern for data that changes frequently:
* Fetch data on page load
* Add a manual refresh button for user-triggered updates
* Use Inngest workflows for periodic background syncs (e.g., sync Salesforce data every 15 minutes)
> Add a "Refresh" button that re-fetches the data from the API. Also show a "Last updated" timestamp.
### File handling in memory
You cannot upload files to local disk storage, but you can process them in the browser:
* Accept file input through an `` element
* Parse the file contents in memory (CSV, JSON, etc.)
* Store the extracted data in the database
* For file storage, use an external service (like S3) via Custom API integration
> Create a CSV import page. Let users upload a CSV file, preview the parsed data in a table, and save it to the database on confirmation.
### User context from the session
Every request in a deployed Vybe app includes the authenticated user's email. Use this to build user-specific experiences:
* Read the user email from the request headers
* Match it against a `users` table in your database for user-specific settings, preferences, or roles
> Show only the tasks assigned to the currently logged-in user. Match the user by their email address from the session.
### Connecting unsupported services
If a service does not have a built-in Vybe integration, you can still connect to it:
1. Create a Custom API integration with the service's base URL and authentication credentials
2. Ask the AI to call the service's REST endpoints directly
3. Store the credentials securely as environment variables
> Connect to our internal API at `https://api.example.com`. Use the API key stored in environment variables. Fetch the list of products from `/v1/products`.
Any service with a REST API can be connected to Vybe through Custom APIs. Check the service's developer documentation for endpoint details and authentication requirements.
***
## What Vybe is best at
Understanding what Vybe is designed for helps you make the most of the platform:
* **Internal dashboards** — KPI tracking, analytics, monitoring
* **CRUD applications** — Customer management, inventory tracking, order management
* **Admin panels** — User management, content moderation, configuration interfaces
* **Data tools** — Report builders, data explorers, import/export workflows
* **Workflow tools** — Approval flows, ticketing systems, task management
* **Integration hubs** — Unified views across Salesforce, Jira, Slack, Stripe, and more
Vybe is not designed for public-facing applications, consumer products, or high-traffic websites. It is purpose-built for internal tools used by your team.
***
## What's next
* See the full list of available packages: [Available Packages](/tips/available-packages)
* Troubleshoot common issues: [Troubleshooting](/tips/troubleshooting)
* Review the tech stack: [Tech Stack Reference](/reference/tech-stack)
# Prompting Best Practices
Source: https://docs.vybe.build/tips/prompting
Write effective prompts that help the AI build exactly what you need
The quality of your prompts directly shapes the quality of your app. A well-crafted prompt gives the AI the context it needs to generate accurate, production-ready code on the first try. A vague prompt leads to guesswork and extra iteration.
This guide covers the techniques that consistently produce the best results.
***
## Be specific and descriptive
The most common prompting mistake is being too general. Compare these two prompts:
> Make a dashboard.
vs.
> Create a dashboard that displays our PostgreSQL customer data in a filterable table with columns for name, email, plan type, and last login date. Add a search bar at the top and dropdown filters for plan type.
The first prompt forces the AI to guess your data source, layout, columns, and functionality. The second prompt gives the AI everything it needs to build the right thing immediately.
A good rule of thumb: if another developer could not build what you described without asking follow-up questions, your prompt needs more detail.
***
## Start with the big picture, then refine
You do not need to describe every detail upfront. The best workflow is to build incrementally:
Start with a prompt that outlines the core purpose and structure.
> Build a project management tool with a sidebar listing all projects and a main area showing tasks for the selected project.
Follow up with targeted prompts that add detail or adjust behavior.
> Add a status badge to each task. Use green for "done", yellow for "in progress", and gray for "todo".
Continue refining until the app matches your expectations.
> Make the task list sortable by due date. Add a button to create new tasks with a modal form.
This approach works better than trying to describe everything in a single prompt because it lets you course-correct at each step.
***
## Describe data relationships
When your app involves structured data, describe how entities relate to each other. This helps the AI design the right database schema and UI.
> Create a project management tool. Projects have multiple tasks. Each task has a title, description, status (todo/in-progress/done), assignee email, and due date. Show tasks in a kanban board grouped by status.
> Build an inventory tracker. Each product belongs to a category and has a name, SKU, quantity, price, and restock threshold. Show a warning badge when quantity drops below the restock threshold.
The more clearly you define your data model, the fewer revisions you will need.
***
## Reference existing code
When you want to modify something that already exists in your app, reference it directly:
> Update the customers page to add a delete button for each row. Show a confirmation dialog before deleting.
> On the dashboard page, change the revenue chart from a bar chart to a line chart.
> Make the sidebar navigation on the settings page collapsible.
The AI has full access to your codebase, so referencing specific pages or components by name helps it find and modify the right files.
***
## Include design preferences
If you have specific layout or styling preferences, mention them in your prompt:
> Use a clean card layout with a sidebar navigation. Keep the color scheme minimal with a white background and subtle gray borders.
> Display the data in a compact table with alternating row colors. Add hover highlighting and make the header sticky.
> Create a two-column layout — filters on the left, results on the right. Use the full width of the page.
The AI defaults to clean, professional layouts using Shadcn UI components, but explicit design direction produces results closer to what you have in mind.
***
## Use Agent mode for building, Ask mode for understanding
Vybe offers two interaction modes, and knowing when to use each saves time:
**Agent mode** is for when you want the AI to create or modify code:
> Add a new page that shows a summary of all orders from the last 30 days.
**Ask mode** is for when you want to understand something without changing it:
> How does the authentication flow work in this app?
> What API routes are currently defined?
Switch to Ask mode before exploring unfamiliar parts of your app. Once you understand the code, switch back to Agent mode to make changes confidently.
***
## Handle errors effectively
When things go wrong, give the AI clear information about the problem:
**If the preview shows an error:**
* Click the error message to automatically send it to the AI
* Or describe what you see: "The page shows a 500 error when I click the submit button"
**If something does not look right:**
* Describe the gap between what you expected and what you see
* "The table is showing all users instead of just active ones. Filter it to only show users where status is 'active'."
**If the AI's output is wrong:**
* Be specific about what needs to change rather than starting over
* "The date format is wrong — use MM/DD/YYYY instead of ISO format"
***
## Iterate, do not restart
Building incrementally is almost always faster than starting over:
* Each follow-up prompt builds on the context from your previous conversation
* The AI remembers what it has already built and can modify it precisely
* Starting a new thread loses that accumulated context
Avoid the temptation to start fresh when something goes wrong. Instead, describe the issue and let the AI fix it. The AI is better at fixing code it wrote than rebuilding from scratch.
***
## Prompt templates for common tasks
Here are starting points for common internal tool patterns:
**CRUD application:**
> Build a \[resource] management page. Display \[resource]s in a data table with columns for \[fields]. Add search, filters for \[filter fields], and buttons to create, edit, and delete \[resource]s.
**Dashboard with charts:**
> Create a dashboard showing \[metrics] from \[data source]. Include a \[chart type] chart for \[metric], summary cards at the top for \[KPIs], and a date range filter.
**Form-based workflow:**
> Build a \[workflow name] form with fields for \[field list]. When submitted, save the data to the database and show a success toast. Add validation for \[required fields].
**Data import tool:**
> Create a page where users can paste CSV data with columns \[column list]. Parse the data, show a preview table, and let them confirm before saving to the database.
***
## What's next
* Learn which UI components are available: [Building Effective UIs](/tips/building-uis)
* Understand the AI's capabilities and modes: [Working with the AI](/tips/working-with-ai)
* Choose the right model for your task: [Choosing a Model](/building-apps/choosing-a-model)
# Troubleshooting
Source: https://docs.vybe.build/tips/troubleshooting
Solutions to common issues you may encounter when building with Vybe
This page covers the most common issues you may run into while building with Vybe, along with steps to resolve them.
***
## Common issues
The live preview may fail to load for several reasons:
1. **The sandbox is starting up.** The development sandbox takes a few seconds to initialize when you first open an app or after a period of inactivity. Wait a moment and the preview will load automatically.
2. **A server error is preventing the page from rendering.** Open the **Logs** tab in the editor to check for server-side errors. If you see errors, describe them to the AI:
> The preview is not loading. The logs show a "Cannot find module" error. Can you fix it?
3. **A build error is blocking the preview.** Ask the AI to run a type check:
> Run a type check and fix any errors.
4. **The page has a client-side error.** Open your browser's developer console (F12) to check for JavaScript errors. Send any error messages to the AI for debugging.
If none of these steps help, try refreshing the page or creating a new browser tab.
Deployment can fail if your app has unresolved code issues.
1. **Run type checks before deploying.** Ask the AI to verify your code:
> Run a type check on the project and fix any issues before I deploy.
2. **Check the deployment details.** When a deployment fails, the deployment status page shows the specific error message and the build step that failed. Use this information to guide the AI:
> The deployment failed with this error: \[paste error]. Can you fix it?
3. **Common causes of build failures:**
* Missing imports or undefined variables
* TypeScript type errors
* Incorrect API route function signatures
* References to files that have been deleted
Make it a habit to ask the AI to run type checks before every deployment. This catches most issues before they reach the build step.
If an integration is not working or data is not flowing:
1. **Verify you completed the connection flow.** Go to the Integrations page and check that the integration shows as connected. For OAuth-based integrations, you may need to re-authorize if the token has expired.
2. **Check visibility settings.** Integrations can be scoped to "You only" or shared with the organization. If another team member cannot use an integration, it may need its visibility updated.
3. **For database connections:**
* Verify the connection string is correct (host, port, database name, credentials)
* Check that your database's firewall allows connections from Vybe's IP addresses
* For SSH tunnels, confirm the public key is added to the server's `authorized_keys` file
4. **For third-party services:**
* Confirm the API credentials are valid and have not been rotated
* Check that the required scopes or permissions are granted
* Review the service's status page for outages
If the AI's output does not match what you asked for:
1. **Be more specific.** Vague prompts lead to guessed implementations. Add detail about the exact behavior, layout, or data you expect.
2. **Reference specific files.** Instead of "update the customers page," try:
> Update `src/app/customers/page.tsx` to add a delete button in the last column of the table.
3. **Break it down.** Large, multi-step requests are more prone to errors. Split them into smaller prompts:
> First, add the delete button to each row.
Then:
> Now add a confirmation dialog that appears when the delete button is clicked.
4. **Switch models.** If the current model is struggling, try Opus 4.5 - High for more careful reasoning, or a different provider for a fresh approach.
5. **Start a new thread.** If the conversation has become long and cluttered, a new thread gives the AI a cleaner context to work from.
If you are approaching your credit limit:
1. **Switch to a cheaper model.** Haiku 4.5 uses the fewest credits per interaction. Use it for simple edits and quick questions.
2. **Use Ask mode for questions.** Ask mode interactions typically consume fewer credits than Agent mode since the AI does not execute tools.
3. **Check your plan.** Review your plan's credit allocation and renewal schedule in your organization settings.
4. **Upgrade your plan.** If you consistently hit your credit limit, a higher-tier plan provides more credits per billing cycle.
Credit usage varies by model and response length. Complex interactions with Opus 4.5 - High use significantly more credits than simple Haiku 4.5 queries.
If queries against a connected external database are not working:
1. **Verify the connection string.** Go to Integrations and confirm the host, port, database name, and credentials are correct.
2. **Check read-only mode.** If the connection is configured as read-only, write operations (INSERT, UPDATE, DELETE) will be blocked. This is intentional for data safety.
3. **For SSH tunnels:**
* Confirm the SSH host and port are accessible from Vybe
* Verify the public key is in the remote server's `~/.ssh/authorized_keys`
* Check that the SSH user has permission to forward connections
4. **For Amazon Redshift:**
* Verify IAM role permissions if using IAM-based authentication
* Check that the Redshift cluster is publicly accessible or reachable from Vybe's network
5. **Test with a simple query.** Start with `SELECT 1` to verify basic connectivity before running complex queries.
If your deployed app looks outdated:
1. **Confirm you deployed after making changes.** Changes in the editor are not automatically deployed. Click **Deploy** to publish the latest version.
2. **Check deployment status.** The deployment may still be building. Wait for it to complete before testing.
3. **Clear your browser cache.** Cached assets may show an older version. Try loading the app in an incognito window or hard-refresh the page (`Cmd+Shift+R` on macOS, `Ctrl+Shift+R` on Windows).
4. **Check the deployment URL.** Make sure you are visiting the correct deployment URL, not an old preview link.
If you added or modified database tables but the changes are not reflected:
1. **Ask the AI to apply the migration.** Schema changes need to be applied to the database:
> Apply the pending database migration.
2. **Check for migration errors.** The AI will report if a migration fails due to conflicts or invalid SQL.
3. **Verify in the Data tab.** Open the Data tab in the editor to see the current database schema and confirm your changes are applied.
If the preview takes a long time to load or the app feels sluggish:
1. **Check your data queries.** Large, unfiltered queries are the most common cause of slow pages. Add pagination, filters, or limits:
> Add pagination to the customers table — show 25 rows per page.
2. **Look for unnecessary re-renders.** If using client components with frequent state updates, ask the AI to optimize:
> The dashboard feels slow. Can you check for performance issues and optimize the rendering?
3. **Add loading states.** While data fetches, show skeleton loaders or spinners so the page feels responsive:
> Add loading skeletons while the data is being fetched.
***
## Getting more help
If you cannot resolve an issue using the steps above:
* **Ask the AI.** Describe the problem in detail and the AI will investigate your code, logs, and configuration to find the root cause.
* **Contact support.** Reach out to the Vybe team at [team@vybe.build](mailto:team@vybe.build) with a description of the issue and any relevant error messages.
***
## What's next
* Review platform constraints: [Platform Limitations](/tips/platform-limitations)
* Improve your prompting: [Prompting Best Practices](/tips/prompting)
* Understand the AI models: [AI Models Reference](/reference/ai-models)
# Working with the AI
Source: https://docs.vybe.build/tips/working-with-ai
Strategies for productive AI collaboration — modes, models, and workflow tips
The AI in Vybe is more than a code generator. It is a collaborative partner that can build, debug, explain, and iterate on your app. Getting the most out of it means understanding how it works and adapting your workflow accordingly.
***
## Agent mode vs. Ask mode
Vybe has two interaction modes, and switching between them at the right time makes a real difference.
### Agent mode (default)
In Agent mode, the AI can create, edit, and delete files, run database queries, install packages, and connect integrations. Use it whenever you want the AI to make changes to your app.
> Add a new page that lists all orders from the last 30 days with status filters.
### Ask mode
In Ask mode, the AI can read your code and answer questions, but it cannot make any changes. Use it when you want to understand your app without risking unintended modifications.
> How does the authentication flow work in this app?
> What database tables are currently defined?
> Explain what the `/api/customers` route does.
Use Ask mode as a learning tool. Before modifying a complex part of your app, switch to Ask mode and ask the AI to walk you through how it works. Then switch back to Agent mode and make your changes with confidence.
***
## Choosing the right model
Different models have different strengths. Picking the right one for the task at hand saves time and credits.
| Model | Best for | Speed | Credit cost |
| ---------------------- | --------------------------------------------- | -------- | ----------- |
| **Opus 4.5** (default) | Complex features, architecture, debugging | Moderate | Higher |
| **Opus 4.5 - High** | Particularly difficult bugs, design decisions | Slower | Highest |
| **Sonnet 4.5** | Straightforward additions, UI tweaks | Faster | Moderate |
| **Haiku 4.5** | Simple edits, quick questions | Fastest | Lowest |
| **GPT-5.1** | Alternative perspective, fresh approach | Moderate | Higher |
| **Gemini 3 Pro** | Another alternative model | Moderate | Moderate |
**A practical workflow:**
1. Start with **Opus 4.5** when building new features or tackling complex logic
2. Switch to **Sonnet 4.5** for UI adjustments and straightforward changes
3. Use **Haiku 4.5** for quick questions and minor text edits
4. Escalate to **Opus 4.5 - High** when the standard model struggles with a problem
5. Try **GPT-5.1** or **Gemini 3 Pro** if you want a different approach to a tricky problem
For the full model reference, see [AI Models Reference](/reference/ai-models).
***
## Understanding locked files
Certain system files in your app are locked and cannot be edited by you or the AI:
* `package.json` — manages dependencies
* `next.config.ts` — Next.js configuration
* `tsconfig.json` — TypeScript configuration
* Middleware configuration files
These files are locked to keep your app's infrastructure stable and compatible with the Vybe platform. The AI is aware of these restrictions and will not attempt to modify them.
If you need functionality that would normally require changes to a locked file (like adding a new npm package), ask the AI. It knows the pre-approved packages and can install them through the proper channel.
***
## When the AI asks you questions
Sometimes the AI needs more information before it can proceed. When this happens, it presents interactive forms with options to choose from or fields to fill in.
For example, if you ask "add user authentication," the AI might ask:
* What fields should the user profile include?
* Should users sign up with email/password or OAuth?
* What pages should be protected?
These questions help the AI make better decisions. Take the time to answer thoughtfully — it results in code that matches your requirements more closely.
You can always provide custom input beyond the suggested options if none of the choices fit your needs.
***
## Handling errors
Errors are a normal part of building apps. Here is how to handle them efficiently:
### Preview errors
If the live preview shows an error, click the error message to send it directly to the AI. The AI can read the error, trace it to the source, and fix it — often in a single step.
### Build and type errors
Before deploying, ask the AI to run type checks:
> Run a type check on the project and fix any errors.
This catches issues like missing imports, incorrect types, and broken API route signatures before they reach production.
### When the AI gets stuck
If the AI produces incorrect output or seems confused:
1. **Rephrase your request** — try describing the same goal from a different angle
2. **Reference specific files** — "Update `src/app/customers/page.tsx` to add a delete button for each row"
3. **Break it down** — split a complex request into two or three simpler steps
4. **Switch models** — Opus 4.5 - High or a different provider may handle the problem better
5. **Start a new thread** — if the conversation has become cluttered, a fresh thread can help
If the AI repeatedly fails at a task, avoid repeating the exact same prompt. Change your approach — add more context, simplify the request, or try a different model.
***
## Thread management
Each app can have multiple conversation threads. Use threads to keep your work organized:
* **One feature per thread** works well — it keeps the conversation focused and the context relevant
* **Create a new thread** when switching to a different topic or feature area
* **Return to old threads** to continue work — the AI retains the full conversation history
* **Use descriptive names** for threads so you can find them later
Code changes apply to the app regardless of which thread initiated them. Threads organize your conversations, not your codebase.
***
## Getting the most out of each interaction
### Give context upfront
Instead of making the AI discover context through trial and error, provide it in your prompt:
> The customers page currently shows a table with name and email. Add a "Plan" column that reads from the `plan_type` field in the customers table.
### Be explicit about behavior
Describe not just what something should look like, but how it should behave:
> When the user clicks Delete, show a confirmation dialog. If they confirm, call the delete API and show a success toast. If the API fails, show an error toast and keep the row in the table.
### Use follow-up prompts for refinement
The AI responds better to iterative refinement than to monolithic prompts:
1. "Build a customer list page with a data table."
2. "Add search and filter by plan type."
3. "Add a detail view that opens when you click a row."
4. "Add edit and delete functionality to the detail view."
Each step builds on the previous one, and you can course-correct along the way.
***
## What's next
* Learn prompting techniques: [Prompting Best Practices](/tips/prompting)
* Understand platform constraints: [Platform Limitations](/tips/platform-limitations)
* Troubleshoot common issues: [Troubleshooting](/tips/troubleshooting)
# Creating Workflows
Source: https://docs.vybe.build/workflows/creating-workflows
Create scheduled jobs and event-driven functions using the AI chat
You create workflows by describing what you need to the AI in chat. The AI generates the Inngest function, configures the trigger, and wires it into your app.
***
## Creating a workflow with AI
Describe what you need in plain language:
> "Create a workflow that syncs our Salesforce contacts every hour."
> "Set up a daily job that sends a Slack summary of open tickets at 9 AM."
> "Add a workflow that sends a welcome email when a new user is added to the database."
The AI creates the function, sets up the trigger, and registers it. You can view the generated code in the Code tab and test it in the sandbox.
***
## Workflow structure
Workflows are Inngest functions stored in your app's `/inngest/functions` directory. Here is a scheduled workflow example:
```typescript theme={null}
import { inngest } from './client';
export const syncContacts = inngest.createFunction(
{ id: 'sync-contacts' },
{ cron: '0 * * * *' }, // Every hour
async ({ step }) => {
const contacts = await step.run('fetch-contacts', async () => {
// Fetch contacts from Salesforce
const response = await fetch('https://api.salesforce.com/contacts', {
headers: {
Authorization: `Bearer ${process.env.SALESFORCE_TOKEN}`,
},
});
return response.json();
});
await step.run('update-database', async () => {
// Update local database with fetched contacts
for (const contact of contacts) {
await db.contact.upsert({
where: { externalId: contact.id },
update: { name: contact.name, email: contact.email },
create: { externalId: contact.id, name: contact.name, email: contact.email },
});
}
});
}
);
```
Each workflow has three parts:
| Part | Purpose |
| ------------------- | ------------------------------------------ |
| **Function config** | A unique ID and optional name |
| **Trigger** | A cron schedule or an event name |
| **Handler** | The logic that executes, broken into steps |
***
## Cron scheduling
Scheduled workflows use cron expressions:
| Expression | Schedule |
| -------------- | ------------------------------------ |
| `* * * * *` | Every minute |
| `*/15 * * * *` | Every 15 minutes |
| `0 * * * *` | Every hour |
| `0 9 * * *` | Daily at 9:00 AM (UTC) |
| `0 9 * * 1` | Every Monday at 9:00 AM (UTC) |
| `0 0 1 * *` | First day of every month at midnight |
You don't need to memorize cron syntax — just tell the AI when you want it to run:
> "Run this every weekday at 8 AM."
Cron schedules use UTC time. If your team operates in a specific timezone, mention it in your prompt and the AI will calculate the correct UTC offset.
***
## Event-driven workflows
Event-driven workflows run in response to events emitted by your app:
```typescript theme={null}
import { inngest } from './client';
export const sendWelcomeEmail = inngest.createFunction(
{ id: 'send-welcome-email' },
{ event: 'user/created' },
async ({ event, step }) => {
await step.run('send-email', async () => {
// event.data contains the payload from the event
const { email, name } = event.data;
// Send welcome email logic
});
}
);
```
To trigger an event-driven workflow, your app emits an event from an API route:
```typescript theme={null}
import { inngest } from '@/inngest/client';
// In an API route
await inngest.send({
name: 'user/created',
data: { email: 'jane@example.com', name: 'Jane' },
});
```
The AI sets up both the event emission and the workflow handler when you describe the behavior you want.
***
## Step functions
Workflows are broken into **steps** — discrete units of work managed independently by Inngest. Steps give you:
* **Automatic retries** — Failed steps are retried without re-running earlier steps
* **Durability** — Completed steps are not re-executed on retry
* **Observability** — Each step is tracked separately in the Workflows tab
```typescript theme={null}
async ({ step }) => {
// Step 1: Fetch data
const data = await step.run('fetch-data', async () => {
return await fetchFromExternalApi();
});
// Step 2: Process data (only runs if Step 1 succeeds)
const processed = await step.run('process-data', async () => {
return transformData(data);
});
// Step 3: Save results (only runs if Step 2 succeeds)
await step.run('save-results', async () => {
await db.results.createMany({ data: processed });
});
}
```
Each step should represent a single logical operation — fetching data, transforming it, or saving results.
***
## Error handling and retries
Inngest automatically retries failed steps with exponential backoff, so transient failures like API outages or network timeouts are handled automatically.
If a step continues to fail after all retry attempts, the workflow is marked as failed and error details are visible in the Workflows tab.
For custom error handling, catch errors within the step:
```typescript theme={null}
await step.run('fetch-with-fallback', async () => {
try {
return await fetchFromPrimaryApi();
} catch (error) {
// Fall back to cached data
return await fetchFromCache();
}
});
```
***
## What's next
* [Managing Workflows](/workflows/managing-workflows)
* [Deploying Your App](/deployment/deploying)
# Managing Workflows
Source: https://docs.vybe.build/workflows/managing-workflows
Monitor, test, and manage your workflows from the Workflows tab
The **Workflows** tab in the editor gives you visibility into all registered workflows — execution history, errors, and status.
***
## Viewing your workflows
Open the **Workflows** tab to see all registered workflows. Each entry displays:
| Detail | Description |
| --------------------- | -------------------------------------------------------------------------------------- |
| **Name** | The function name and ID |
| **Schedule** | The cron expression (for scheduled jobs) or event trigger (for event-driven functions) |
| **Recent executions** | A summary of recent runs with status indicators |
***
## Execution history and logs
Each workflow tracks its execution history with three statuses:
* **Success** — All steps completed without errors
* **Failure** — One or more steps failed after all retry attempts
* **Running** — Currently executing
Click on a specific execution to see detailed logs: which steps ran, timing information, and error messages with stack traces for failed steps.
***
## Testing during development
Workflows are synced to your sandbox environment, so you can test them before deploying to production. Scheduled workflows execute on their defined schedule within the sandbox, and event-driven workflows trigger when your sandbox app emits the relevant event.
To test a scheduled workflow without waiting for the next cron tick, ask the AI to trigger it manually or temporarily set the schedule to every minute.
***
## Deploying workflows
Workflows are deployed as part of your app — no separate deployment needed. When you click **Deploy**, Vybe:
1. **Registers** your workflow functions with Inngest
2. **Activates** cron schedules on the production environment
3. **Starts** event listeners for event-driven functions
***
## Disabling workflows
Two options to stop a workflow:
* **From the Workflows tab** — Disable it directly from the UI. Takes effect immediately without removing the code.
* **From the code** — Ask the AI to remove the workflow function. Takes effect on the next deployment.
Disabling a workflow does not delete its execution history. You can still view past runs and logs.
***
## Troubleshooting
If your workflows are not running as expected, check these common issues:
Ensure the workflow function is properly exported and registered in your Inngest configuration. The AI handles this automatically, but if you edited code manually, verify the wiring.
Cron schedules use UTC time. Check the cron expression and account for the timezone difference. Ask the AI to adjust the schedule.
Individual steps have execution time limits. Break long-running operations into smaller steps or optimize them to complete faster.
The event name in your `inngest.send()` call must match the event name in the workflow's trigger configuration exactly.
***
## What's next
* [Creating Workflows](/workflows/creating-workflows)
* [Workflows Overview](/workflows/overview)
* [Deploying Your App](/deployment/deploying)
# Workflows Overview
Source: https://docs.vybe.build/workflows/overview
Run background jobs and scheduled tasks in your Vybe app with Inngest-powered workflows
Workflows let your app run background jobs and scheduled tasks. They are powered by [Inngest](https://www.inngest.com/) and run server-side with full access to your app's database and integrations.
***
## What are workflows
Workflows are functions that run in the background, either on a schedule or in response to events in your app. Common uses include:
* Syncing data from external services on a recurring schedule
* Sending automated email or Slack notifications
* Processing batch data operations
* Cleaning up old records or stale data
* Polling external APIs for updates
***
## Types of workflows
Vybe supports two types of workflows:
| Type | Trigger | Example |
| -------------------------- | ------------------------------- | ------------------------------------------------ |
| **Scheduled jobs (Cron)** | Run on a fixed schedule | Sync Salesforce contacts every hour |
| **Event-driven functions** | Triggered by events in your app | Send a notification when a new record is created |
**Scheduled jobs** use cron expressions to define when they run — every few minutes, hourly, daily, weekly, or on any custom schedule.
**Event-driven functions** listen for events your app emits and run automatically when the event fires.
Vybe does not currently support inbound webhooks. To react to changes in an external system, use a scheduled job to poll the API at regular intervals.
***
## How workflows run
Workflows are deployed alongside your app. When you click **Deploy**, Vybe registers your workflow functions with Inngest, which handles scheduling, execution, and retries.
During development, workflows are synced to your sandbox so you can test them before deploying to production.
***
## Use cases
Common patterns for workflows:
Pull data from external services on a schedule. Sync contacts from Salesforce, tickets from Jira, or transactions from Stripe.
Send Slack messages, emails, or other notifications when conditions are met — overdue tasks, new signups, or threshold breaches.
Process large datasets in the background. Generate reports, aggregate metrics, or transform data on a schedule.
Remove stale records, archive old data, or reset temporary states on a recurring schedule.
***
## What's next
* [Creating Workflows](/workflows/creating-workflows)
* [Managing Workflows](/workflows/managing-workflows)