Setup Emergent App

Setup Emergent app

Emergent apps are real code (often FastAPI + React + Mongo) trapped in an agent-first container. Goal: local run + GitHub as shared truth, without fighting the Emergent agent every hour.

Collaboration law (do this first)

1. One writer on main at a time. Emergent owns main while vibing; you work on feature branches; merge only when Emergent is clean + pushed.
2. Emergent “Pull from GitHub” is for new projects only. On existing projects, sync in the Emergent shell with git (fetch / pull / reset / rebase).
3. Agent awareness: after a shell pull, point the agent at the change (“read path; what does X say?”). It reads the live tree — it is not locked to what it wrote — but it can still stomp edits on the next vibe.
4. Before you merge into main: Emergent on main, clean tree, not ahead of origin/main (pushed). Then merge/push; Emergent git pull --ff-only.
5. Diverged branches: inspect with git log --oneline --left-right HEAD...origin/main. Keep real work (pull --rebase); toss junk agent commits (reset --hard origin/main only after git show proves they’re disposable — backup branch first).

Marker experiment (verify sync + awareness)

Append a loud unique string (e.g. EXT-MARKER-A1) to one visible CTA, push, pull in Emergent shell, ask the agent what the CTA says. Strip after.

Local boot (typical Emergent stack)

Assume: backend/ FastAPI + frontend/ React (CRA/craco) + Mongo 7. Ports often 3000 (FE) / 8001 (API). Prefer CI (.github/workflows) over README — README “local” is often Emergent supervisorctl.

Checklist

Copy and track:

- [ ] Python 3.11 (not 3.14) — `py -0` / `py -3.11`
- [ ] Docker Mongo 7 on 27017
- [ ] backend/.env (gitignored)
- [ ] frontend/.env → REACT_APP_BACKEND_URL=http://localhost:8001
- [ ] backend venv + deps (private pip index)
- [ ] yarn install + yarn start
- [ ] Smoke: :8001/docs and :3000

Env (minimum)

backend/.env — never commit:

MONGO_URL=mongodb://localhost:27017
DB_NAME=<app>_local
JWT_SECRET=local-dev-jwt-not-for-prod
MASTER_RECOVERY_TOKEN=local-dev-master-token
CORS_ORIGINS=http://localhost:3000

Add Stripe/Twilio/Mux/etc. only when needed. Prefer placeholders for browse-only.

frontend/.env:

REACT_APP_BACKEND_URL=http://localhost:8001

Watch for 8081 vs 8001 typos.

Python / pip

cd backend
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

Private package: emergentintegrations is not on public PyPI. User pip config (%APPDATA%\pip\pip.ini on Windows):

[global]
extra-index-url = https://d33sy5i8bnduwe.cloudfront.net/simple/

(Source: Emergent’s CDN simple index, also documented via eamicointegrations.)

litellm conflict: if requirements.txt pins litellm @ https://customer-assets...whl#sha256=... and emergentintegrations depends on the same wheel without the hash, pip ResolutionImpossible. Install a filtered copy (gitignored):

(Get-Content requirements.txt) |
  Where-Object { $_ -notmatch '^\s*litellm\s*@' } |
  Set-Content requirements.local.txt
pip install -r requirements.local.txt

Do not re-run full requirements.txt after that succeeds.

Smoke import:

python -c "from server import app; print(getattr(app,'title', app))"

Mongo

docker run -d --name <app>-mongo -p 27017:27017 mongo:7

Idempotent helper: scripts/db-up.bat (rename container).

Frontend

cd frontend
yarn install
yarn start

@emergentbase/visual-edits is often optional in craco — missing is OK.

Windows activate

PowerShell: .\.venv\Scripts\Activate.ps1
Not source (bash). Cmd: .\.venv\Scripts\activate.bat

Dev scripts (local-only)

Prefer gitignored bats so Emergent doesn’t own them. Templates in scripts/:

Copy into the app repo, rename container/ports if needed, gitignore dev.bat, db-up.bat, **/dev.bat, requirements.local.txt.

Prefer no local-only code forks

Env files + Docker + venv + pip config are enough. Only stub/skip emergentintegrations if the private index is unreachable — last resort; Stripe routers often import it at module load.

Security (while setting up)

• memory/test_credentials.md and test_reports/ often leak tokens — don’t copy them into chat; rotate if repo is/was public.
• Don’t commit .env, master tokens, or live Stripe keys.
• Full audit is separate; boot first is fine.

Handoff prompt for Emergent agent

After they git pull --ff-only:

Pulled from GitHub. Treat the repo as source of truth. Re-read the files you will touch. Do not revert unrelated changes.

More

• Bat templates: scripts/
• Failure matrix: reference.md