Platform Documentation

Complete guide to building and deploying on Emergent.sh

Understanding the Basics

What is Preview vs Deployment?

Feature	Preview	Deployment
What it is	Your testing playground	Your live app
How long it lasts	Upto 30 minutes (if there is no interaction), then stops	Always online
Resources (CPU/RAM)	High (more powerful)	Lower (optimized)
URL looks like	yourapp.preview.emergentagent.com	yourapp.emergent.cloud/yourapp.emergent.host
Database	Preview database	Production database
Cost	Only development credits	50 credits ($10) first time (starter tier)

Simple Rule: Preview and deployment are completely separate. When you make changes in preview, you must redeploy to see them live.

Machine Types in Preview (add more context - what and why does the user need to know)

Machine	Power	When to Use
Regular	Standard power	Normal development
Large	Extra power	Testing heavy features

On paid tiers, the switch between machine types happens automatically. On basic tiers, the agent will stop and user must wake up the agent with a larger machine (simple button press)

Before You Deploy

• Agent is awake (deployment won’t work if agent is asleep)
• App works in preview (fix all errors before deploying)
• Not using too much compute (app will shut down if it uses too much) - have to explain what is compute
• Optimize your queries - instruct the agent to write optimized code
• Plan ahead if your database will be large - reach out in advance to ensure your app is deployed smoothly.

Phase 1: Build Phase

What Happens Here?

Your code gets compiled and prepared for production. Think of it like packing your app into a box ready to ship.

What Gets Built	From Where
Frontend (what users see)	Your React code
Backend (the server)	Your Python/FastAPI code
JavaScript packages	package.json file
Python packages	requirements.txt file

Time: ~5 minutes

The Big Problem: Heavy Libraries

In Preview	In Deployment	The Rationale
Heavy libraries work fine (high resources)	Heavy libraries fail (lower resources)	why this is the way it is
Example: Can use pandas, matplotlib	Example: These will timeout or crash

Why This Happens: Deployment has less CPU and RAM than preview. What works in testing might not work when live.
[**Emergent allows users more freedom to create an app and then scale as you grow] **

The Solution: Use APIs Instead

Don’t Install This	Do This Instead
pandas, matplotlib, plotly	Use external data analysis APIs
Large AI/ML libraries	Use OpenAI API, Hugging Face API
Playwright, Selenium	Use external automation services
Heavy image tools	Use Cloudinary or imgix API
Big calculations	Use AWS Lambda or Cloud Functions

Simple Rule: If a library is large, use an API service instead of installing it - say why.

Some Examples of External Services You Can Integrate With

Service Type	Some Examples	What It Does	The Reason
File Storage	Amazon S3, Google Cloud Storage	Store images, videos, PDFs
Databases	Supabase, PostgreSQL	Handle lots of data
File Hosting	Cloudinary	Manage images and media

What is the difference between a db and a storage service - why the investment is worth it to build serious apps.

Some Common Build Errors

Error	What It Means	How to Fix (What to tell the agent)
“Module not found”	Missing from package.json or requirements.txt	Add the missing package
”Build timeout”	App is too heavy	Remove heavy libraries, use APIs
”Syntax error”	Code has mistakes	Fix the code error
”Out of memory”	Using too much RAM	Optimize code, reduce packages

How to Fix Build Problems (with the agent)

1. Share logs with agent

   Use the one-click log sharing button _[add GIF] _or copy logs and share in chat

2. Ask agent to optimize

   Tell the agent to optimize your code

3. Agent identifies the relevant action

   The agent will perform the fix and solve the error

4. Test again

   Verify everything works in preview

5. Perform a one click Health Check

   It is strongly recommended to ask the agent to perform a health check before attempting to deploy again. This ensures the app has a much better chance of a clean deployment.

6. Deploy Your App

   Once solved, attempt to deploy your app again.

Phase 2: Database Migration

What Happens Here?

Your data moves from preview to production. Like moving your furniture to a new house.

Time: 1-2 minutes

What is a Database?

Type	How It Works	How we handle it
Relational	Data in tables (like Excel)	You can connect your own database.
Non-Relational	Data in flexible documents	MongoDB by default

Emergent uses MongoDB by default, which is flexible and easy to work with.

How Our Databases Work

What You Need to Know	Details
Shared hosting	Multiple users share the same cluster - simplify
Preview vs deployment	They are completely separate databases
Built-in storage	Can store large amounts of text & limited files, images, PDFs in MongoDB - replace with a better explanation - _why we suggest external connections. _
Queries must be optimized	Slow queries will fail during deployment

Important: The agent cannot see your deployed database unless you share logs. Preview and deployment are separate environments.

When Databases Get Too Heavy

Problem	Solution
Storing many large images	Use Amazon S3 or Google Cloud Storage
Lots of videos or PDFs	Use file hosting service like Cloudinary
Very large datasets	Use Supabase or PostgreSQL
High traffic app	Get dedicated database (contact support)

Making Queries Optimized

Query Speed	Result	What to Do
Unoptimized queries	Deployment may fail, or timeout	Ask agent to optimize
Optimized queries	Deployment has improved performance	Ready to go

How to Optimize: Tell the agent “optimize my database queries” and it will rewrite them better.

Common Database Errors (shows up in logs, share with agent to fix)

Error	What It Means	How to Fix (Ask the agent)	Simple Fix
”Connection failed”	Can’t connect to database	Check MONGO_URL in .env file	Fork and Replace deployment
”Query timeout”	Query too slow	Ask agent to optimize queries
”Schema error”	Data format is wrong	Ask agent to fix

Connecting Your Own Database

1. Get credentials

   Get URL and password from your database provider

2. Share with agent

   Provide credentials to the Emergent agent

3. Agent configures

   Agent sets up the connection

4. Test connection

   Verify it works in preview

5. Deploy

   Deploy with your custom database

Phase 3: Exporting Secrets

What Are Secrets?

Secrets are passwords, API keys, and settings your app needs. They go in the .env file.

Time: 1-2 minutes

Two Types of Secrets

Type	Examples	Who Provides
Emergent gives you	MongoDB URL, Backend URL, Port, CORS	Automatic
You provide	API keys, your database passwords, external services	You

The Golden Rules

Never put secrets in code

Anyone can see them (security risk)

Always use .env files

Easy to change, stays private

Be very careful editing

One wrong character breaks everything

Must redeploy after changing

Changes only work after you redeploy

What Breaks Your App

If This is Wrong	This Happens
Port number	App can’t connect
URL	You get 404 errors
API key	External services don’t work
Database URL	Can’t load any data

Be careful! Double-check everything before deploying.

Common Secret Errors

Error	What It Means	How to Fix
”Missing variable”	You forgot to add it to .env	Add the missing variable
”Invalid API key”	Key is wrong or expired	Get a new valid key
”Connection refused”	URL or port is wrong	Fix the URL or port number

Best Practices

Test API keys before deploying

Make sure they work by testing them in preview first

Keep a backup of .env file

Save a copy in case you need to restore settings

Name variables clearly

Use descriptive names so you know what each does

Update URLs after changing domains

External services need to know your new domain

Phase 4: Deploy and Health Check

Deploy: Setting Up Infrastructure

Your app is launched on servers and made available to the world.

What Happens:

• Servers are set up (Kubernetes)
• Your app is installed on servers
• Network connections are configured
• Resources (CPU/RAM) are assigned

Time: 3-5 minutes

Common Deploy Errors

Error	What It Means	How to Fix
”Provisioning failed”	Server setup problem	Wait and try again, contact support if it keeps failing
”Container crashed”	App won’t start	Check logs, fix startup code
”Port conflict”	Port already being used	Check port settings
”Out of resources”	App needs too much power	Optimize app, use external APIs

Health Check: Is Everything Working?

After deployment, the system checks if your app is actually working.

What Gets Checked:

• App responds to requests
• APIs are working
• Frontend loads correctly
• Database is connected
• All services are running

Time: 1-2 minutes

If Health Check Fails

Problem	What It Means	How to Fix
”App crashed”	Code error on startup	Review logs, fix the error
”API error 500”	Backend has problems	Check backend code
”White screen”	Frontend won’t load	Check frontend build
”Database failed”	Can’t connect to database	Verify connection info
”CORS error”	Security settings wrong	Fix CORS configuration

Important: If health check fails, your app won’t go live. This protects you from publishing a broken app.

Total Deployment Time

All Phases Combined	Typical Time
Build + Database + Secrets + Deploy + Health Check	10-15 minutes

Understanding Deployment Costs

How Much Does It Cost?

What	Cost	When You Pay
First time you deploy	50 credits ($10)	Once per app
Update same app (redeploy)	FREE	Every time after first
Deploy a new app	50 credits ($10)	Once per new app

What Do You Get for 50 Credits?

24/7 Uptime

Your app runs always online

Database Hosting

Managed MongoDB included

Build Pipeline

All deployment steps included

Custom Domains

Auto-linking for your domains

Good News: After paying once, you can update your app unlimited times for free.

What Happens When You Redeploy?

This Updates	This Stays the Same
Your code (frontend and backend)	Your database (from first deployment)

Important: Redeploying updates your code but NOT your database.

If you changed data in preview after your first deployment, that data won’t appear in production. You need to manually move it.

Replacing Existing Deployments

Why Replace Instead of Deploy New?

Scenario: You forked your app, made it better, and want the new version to replace the old one WITHOUT paying another 50 credits.

Your Options

Option	When to Use	What Happens to Data
Fresh start	No important data to keep	Old data deleted, start fresh
Keep old data	Users have important data	Old data stays
Merge data	Want old AND new data together	Combines both databases

Option 1: Fresh Start (Copies Preview Data)

1. Replace deployment

   Click “Replace Existing Deployment”

2. Choose fresh database

   Select “Fresh Database” option

3. Deploy

   New app replaces old one

Result: Old app gone, new app live, no extra charge.

Option 2: Merge Old and New Data

1. Request export

   Email [e-mail] to export data (up to 24 hours)

2. Download data

   Get your data when ready (few minutes)

3. Share with agent

   Give data to agent, ask to merge

4. Check for conflicts

   Tell agent to verify no data conflicts

5. Deploy merged data

   Deploy with combined database

Result: All data preserved, no extra charge.

Option 3: Zero Risk Method (High Traffic Apps)

1. Export old data

   Request from support (time only)

2. Deploy new app separately

   Deploy as standalone (50 credits)

3. Add old data

   Load exported data to new app

4. Verify everything

   Check all data and features work

5. Turn off old app

   Shut down old app (free)

Result: Zero downtime, zero data loss, but costs 50 credits.

Working with URLs and Domains

The Three Types of URLs

URL Type	Looks Like	When It’s Online	Power
Preview	app.preview.emergentagent.com	30 minutes only	High
Deployed	app.emergent.host	Always	Normal
Your domain	yourdomain.com	Always	Normal

Adding Your Own Domain

1. Buy a domain

   Purchase from GoDaddy, Namecheap, etc (right away)

2. Change DNS settings

   Update at your domain provider (right away)

3. Auto-link in Emergent

   Use Emergent dashboard (5-10 minutes)

4. Wait for propagation

   DNS spreads worldwide automatically (10 min to 2 hours)

After You Link Domain: Update all external services (APIs, payment processors, OAuth) to use your new domain instead of the old emergent.host URL.

Troubleshooting Guide

Quick Problem Solver

Problem	Quick Fix
Build fails	Share logs with agent, check for missing packages
Database fails	Check MONGO_URL, ask agent to optimize queries
Deploy fails	Check logs, contact support if it keeps happening
App won’t start	Check .env file for wrong values
Domain doesn’t work	Wait 10 min to 2 hours for DNS to update
APIs stop working	Update URLs at external service providers
Preview shuts down	Use Large machine or make app lighter
Can’t deploy	Wake up the agent first

When to Share Logs

Problem	What Logs Show
Build fails	What packages are missing
Database fails	What queries are slow
Deploy fails	What infrastructure problem occurred
App crashes	What code error happened

How: Click the one-click log share button, send to agent, agent tells you how to fix.

When to Email Support

Email [e-mail] when:

Problem	What to Include
Same error keeps happening	Job ID, logs, what you tried
Server/infrastructure issues	Job ID, error message
Need to export database	Job ID, how big your database is
Want dedicated database	How much traffic you have
Domain problems	Your domain name, DNS settings

Pre-Deployment Checklist

• Works perfectly in preview (catch problems early)
• Database queries are fast (prevent timeouts)
• Using APIs instead of heavy libraries (avoid crashes)
• All packages listed in config files (prevent build errors)
• API keys work (make sure integrations function)
• Secrets in .env file, not code (security)
• Agent is awake (can’t deploy if agent is asleep)

Quick Reference

Key Terms Simple Guide

Term	What It Means
Preview	Testing area, stops after 30 min, high power
Deployment	Live app, always on, normal power
Redeploy	Update your code for free (same app)
Job ID	Your app’s unique number
Heavy library	Big package that works in preview but fails when deployed
External API	Service you connect to instead of installing locally
.env file	Where you store passwords and keys
Agent	AI helper that builds and fixes your app