# Setup Emergent App

> Bring an Emergent.sh vibecoded app into a real local+GitHub workflow: dual-writer handoffs, Python/Mongo/React local boot, private emergentintegrations pip index, Windows dev scripts. Use when the user mentions Emergent, emergent.sh, vibecoding handoff, running an Emergent app locally, Pull from GitHub only for new projects, or emergentintegrations install failures.

- Skill: `spencer1o1/setup-emergent-app` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add spencer1o1/setup-emergent-app`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spencer1o1/setup-emergent-app/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Spencer1O1 (https://skillmd.com/u/spencer1o1)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/spencer1o1/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

```powershell
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):

```powershell
(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:

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

### Mongo

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

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

### Frontend

```powershell
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/](scripts/):

| File | Role |
|------|------|
| `db-up.bat` | create/start Mongo container |
| `backend-dev.bat` | activate venv + uvicorn `:8001` |
| `frontend-dev.bat` | `cd` + `yarn start` |
| `dev.bat` | db-up → start backend + frontend windows |

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/](scripts/)
- Failure matrix: [reference.md](reference.md)