preview-dev

$2b

When user reports a problem:

• DIAGNOSE FIRST — read_file the HTML/code, use preview_check to get diagnostics

• FIX IN PLACE — edit_file the existing file, do NOT create a new file

• RESTART SAME PREVIEW — preview_stop(old_id) then preview_serve with SAME dir/port

• 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

When something goes wrong, follow this exact sequence:

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

Symptom

Likely Cause

Fix

White/blank page

JS error, CDN blocked, script escape

Read HTML, fix the script tag

Directory listing

Missing command+port, wrong dir

Add command+port or fix dir path

404 on resources

Absolute paths

Change /path to ./path

CORS error

Direct external API call

Add backend proxy endpoint

Connection failed

Service didn't start

Check command, port, dependencies

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

Tools: read_file, write_file, edit_file, bash, preview_serve, preview_stop, preview_check

Project Type Quick Reference

Type

command

port

Example

Static HTML/CSS/JS

(omit)

(omit)

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

Vite/React/Vue

npm install && npm run dev

5173

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

Backend (Python)

pip install ... && python main.py

from code

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

Backend (Node)

npm install && node server.js

from code

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

Fullstack

build frontend + start backend

backend port

See fullstack section below

Streamlit

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

8501

Gradio

pip install gradio && python app.py

7860

Fullstack Projects

Key Principle: Single Port Exposure. Backend serves both API and frontend static files on one port.

Steps:

• Build frontend: cd frontend && npm install && npm run build

• Configure backend to serve frontend/dist/ as static files

• Start backend only — single port serves everything

FastAPI:

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

Express:

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 call:

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 /)

Cause: Built-in static server serving source directory instead of web page.

Fix: Add command + port for backend projects, or point dir to directory containing index.html.

Must Use Relative Paths

Preview is reverse-proxied through /preview/{id}/. Absolute paths bypass the proxy.

Location

❌ Wrong

✅ Correct

HTML src/href

"/static/app.js"

"static/app.js" or "./static/app.js"

JS fetch

fetch('/api/users')

fetch('api/users')

CSS url()

url('/fonts/x.woff')

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

Vite: base: './' in vite.config.js

CRA: "homepage": "." in 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

Frontend: Browsers block cross-origin requests from iframes (CORS). Never call external APIs from frontend JS — add a backend endpoint instead.

Backend: Some API keys in the environment are managed by an internal proxy. Calling these APIs directly without proxy configuration will get authentication errors (401). Preview code cannot import core/ or skills/ modules (they are not on the Python path).

How to fix: Read core/http_client.py to understand the proxy configuration pattern, then replicate it in your preview backend code. The key functions to replicate are _get_proxy_config() and _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')

For live data previews: Build a backend (FastAPI/Express) that configures the proxy (see core/http_client.py for the pattern) and exposes API endpoints.

API Polling Costs Credits

If code includes setInterval, auto-refresh, or polling, MUST notify the user about ongoing credit consumption. Prefer manual refresh buttons.

Rules (MUST follow)

-

Modify in-place, don't create new projects. Use edit_file in the current project. Don't create new directories or version files.

-

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.

-

Restart on the same port. Same dir, command, port as before. Don't change port numbers.

-

port MUST match the code. Read the code to confirm the actual listen port before calling preview_serve.

-

Listen on 127.0.0.1 only. Do NOT use --host 0.0.0.0.

-

Port conflict is auto-resolved. Same-port and same-directory previews are automatically cleaned up.

-

Backend projects MUST have command + port. Only pure static HTML can omit command.

-

No placeholders. Ever. Every line of code must actually run.

-

Verify after starting. Check health_check in the preview_serve response. If not ok, fix before telling the user.

-

Env vars are inherited. Use os.getenv(). No dotenv loading needed.

-

One preview, one port. Fullstack = backend serves frontend static files + API on single port.

-

Max 3 command-based previews. Oldest auto-stopped when exceeded. Use preview_stop to clean up.

-

Read before editing. read_file first to understand context before making changes.

-

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

After a preview is working, users may want to share it publicly. Use community_publish to create a permanent public URL.

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)

Community publish uses a completely separate route from preview:

• Preview route (/preview/{id}/): cookie auth, for container owner only

• Community route (/community/{port}/): gateway key auth, for public access

The public URL binds to the service port, not the preview ID. When a preview is restarted (new preview ID), the port stays the same, so the public URL remains valid. No need to re-publish after restarting.

Tools

Tool

Purpose

community_publish(preview_id, slug?, title?)

Publish preview to public URL (preview_id is used to look up the port)

community_unpublish(slug)

Remove from public URL (use the full slug with user_id prefix)

community_list()

List all your published previews

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)