Preview Dev — Frontend & Fullstack Development with Live Preview

⛔ MANDATORY CHECKLIST — Execute These Steps Every Time

After preview_serve returns:

1. Check

   health_check

   field in the response
   • If

     health_check.ok

     is false → fix the issue BEFORE telling the user
   • If

     health_check.issue

     is

     "directory_listing"

     → you forgot command+port, or dir has no index.html
   • If

     health_check.issue

     is

     "script_escape_error"

     → fix the HTML escaping
   • If

     health_check.issue

     is

     "blank_page"

     → check JS errors, missing CDN, empty body
   • If

     health_check.issue

     is

     "connection_failed"

     → service didn't start, check command/port
2. Only tell the user "preview is ready" when

   health_check.ok

   is true

When user reports a problem:

1. DIAGNOSE FIRST —

   read_file

   the HTML/code, use

   preview_check

   to get diagnostics
2. FIX IN PLACE —

   edit_file

   the existing file, do NOT create a new file
3. RESTART SAME PREVIEW —

   preview_stop(old_id)

   then

   preview_serve

   with SAME dir/port
4. VERIFY — check

   health_check

   in the response

How to find preview IDs:

• Read the registry:

  bash("cat /data/previews.json")

  — lists all running previews with IDs, titles, dirs, ports
• From previous tool output:

  preview_serve

  returns

  preview_id

  in its response — remember it
• NEVER guess IDs — preview IDs are short hex strings (e.g.

  84b0ace8

  ), not human-readable names

NEVER DO:

• ❌ Create a new script file when the old one has a bug (fix the old one)
• ❌ Create a new preview without stopping the old one first (auto-cleanup handles same-dir, but be explicit)
• ❌ Guess preview IDs — always read

  /data/previews.json

  or use the ID from

  preview_serve

  output
• ❌ Try the same failed approach more than once
• ❌ Call an API directly via bash if a tool already provides it
• ❌ Tell the user "preview is ready" when health_check.ok is false

Error Recovery SOP

Step 1: Diagnose (DO NOT SKIP)

# Check preview health
preview_check(preview_id="xxx")

# Read the actual file to find the bug
read_file(path="project/index.html")

# If needed, check server-side response
bash("curl -s http://localhost:{port}/ | head -20")

Step 2: Identify Root Cause

/path

./path

Step 3: Fix In Place

• Use

  edit_file

  to fix the specific bug
• Do NOT create new files or directories
• Do NOT rewrite the entire project

Step 4: Restart and Verify

preview_stop(preview_id="old_id")
preview_serve(title="Same Title", dir="same-dir", command="same-cmd", port=same_port)
# Check health_check in response — must be ok: true

Core Workflow

1. Analyze requirements → determine project type
2. Write code → create a complete, runnable project
3. Check code to confirm port → read the code to find the actual listen port
4. Start preview → call preview_serve (port MUST match the port in code)
5. Verify → check health_check in response
6. Iterate → modify code in the SAME project, then:
   a. Read /data/previews.json to get the current preview ID
   b. preview_stop(old_id) to stop the old preview
   c. preview_serve with SAME dir and port to restart
   d. Verify health_check again

read_file

write_file

edit_file

bash

preview_serve

preview_stop

preview_check

Project Type Quick Reference

preview_serve(title="Dashboard", dir="my-dashboard")

npm install && npm run dev

preview_serve(title="React App", dir="my-app", command="npm install && npm run dev", port=5173)

pip install ... && python main.py

preview_serve(title="API", dir="api", command="pip install -r requirements.txt && python main.py", port=8000)

npm install && node server.js

preview_serve(title="API", dir="api", command="npm install && node server.js", port=3000)

pip install streamlit && streamlit run app.py --server.port 8501 --server.address 127.0.0.1

pip install gradio && python app.py

Fullstack Projects

1. Build frontend:

   cd frontend && npm install && npm run build

2. Configure backend to serve

   frontend/dist/

   as static files
3. Start backend only — single port serves everything

app.mount("/", StaticFiles(directory="../frontend/dist", html=True), name="static")

app.use(express.static(path.join(__dirname, '../frontend/dist')))
app.get('*', (req, res) => res.sendFile('index.html', {root: path.join(__dirname, '../frontend/dist')}))

preview_serve(
    title="Full Stack App",
    dir="backend",
    command="cd ../frontend && npm install && npm run build && cd ../backend && pip install -r requirements.txt && python main.py",
    port=8000
)

⚠️ Common Issues & Fixes

Directory Listing (Index of /)

command

port

dir

index.html

Must Use Relative Paths

/preview/{id}/

"/static/app.js"

"static/app.js"

"./static/app.js"

fetch('/api/users')

fetch('api/users')

url('/fonts/x.woff')

url('./fonts/x.woff')

base: './'

vite.config.js

"homepage": "."

package.json

Never Tell Users to Access localhost

❌ "Visit http://localhost:5173"
✅ "Check the Browser panel for the preview"

Third-Party API Calls from Preview Code

core/

skills/

core/http_client.py

_get_proxy_config()

_get_ca_file_path()

// ❌ WRONG — frontend cannot call external APIs
fetch('https://api.external.com/data')

// ✅ CORRECT — call your own backend endpoint
fetch('api/stocks?symbol=AAPL')

core/http_client.py

API Polling Costs Credits

setInterval

Rules (MUST follow)

1. Modify in-place, don't create new projects. Use

   edit_file

   in the current project. Don't create new directories or version files.
2. Detect duplicate versions, ask before cleanup. If you find

   app-v2

   ,

   app-v3

   ,

   app-copy

   directories, list them and ask the user whether to delete old versions.
3. Restart on the same port. Same

   dir

   ,

   command

   ,

   port

   as before. Don't change port numbers.
4. port MUST match the code. Read the code to confirm the actual listen port before calling

   preview_serve

   .
5. Listen on 127.0.0.1 only. Do NOT use

   --host 0.0.0.0

   .
6. Port conflict is auto-resolved. Same-port and same-directory previews are automatically cleaned up.
7. Backend projects MUST have command + port. Only pure static HTML can omit command.
8. No placeholders. Ever. Every line of code must actually run.
9. Verify after starting. Check

   health_check

   in the

   preview_serve

   response. If not ok, fix before telling the user.
10. Env vars are inherited. Use

    os.getenv()

    . No dotenv loading needed.
11. One preview, one port. Fullstack = backend serves frontend static files + API on single port.
12. Max 3 command-based previews. Oldest auto-stopped when exceeded. Use

    preview_stop

    to clean up.
13. Read before editing.

    read_file

    first to understand context before making changes.
14. SPA routing needs fallback. Built-in static server handles this automatically. Custom backends need catch-all route returning

    index.html

    .

Community Publish — Share Previews Publicly

community_publish

Workflow

1. preview_serve → verify health_check.ok is true
2. User says "share this" / "publish" / "deploy" / "make it public"
3. Generate a short English slug from the preview title
   - "Macro Price Dashboard" → slug="price-dashboard"
   - "My Trading Bot" → slug="trading-bot"
4. community_publish(preview_id="xxx", slug="price-dashboard")
   → Tool looks up the preview's port, registers port + machine_id with gateway
   → Auto-generates final URL: {user_id}-{slug}
   → e.g. https://community.iamstarchild.com/586-price-dashboard/
5. Tell user the public URL

How It Works (Port-Based Routing)

• Preview route (

  /preview/{id}/

  ): cookie auth, for container owner only
• Community route (

  /community/{port}/

  ): gateway key auth, for public access

Tools

community_publish(preview_id, slug?, title?)

community_unpublish(slug)

community_list()

Slug Generation

• You must generate the slug from the preview title: translate to English, lowercase, hyphens for spaces, keep it short (2-4 words)
• If slug is omitted, preview_id is used as fallback (e.g.

  586-c0bbc1c7

  )
• Final URL format:

  {user_id}-{slug}

  — the tool prepends user_id automatically
• Lowercase letters, numbers, hyphens only, cannot start/end with hyphen

Important Notes

• Preview must be running before publishing
• One port = one slug: each port can only have one public URL; re-publishing with a new slug auto-replaces the old one
• Public URL works as long as the agent container is running — if stopped, visitors see "Preview Offline"
• Max 10 published previews per user
• Public URL has no authentication — anyone with the link can view
• To update: just re-publish with the same slug (it overwrites)

• community_unpublish

  removes the public URL (preview keeps running locally)