Appearance
GhostForge Full Lab
Ten steps. Forty-five minutes. From empty gallery to governed app portal.
This lab walks you through the complete GhostForge experience — enabling the feature, creating and publishing canvas apps, browsing the gallery, forking, embedding, configuring org governance policies, running the approval workflow, viewing analytics, and publishing programmatically via the API.
Prerequisites
Before starting, ensure you have:
- [ ] GhostAI deployment running (backend on port 8000, frontend on port 5173 or 80)
- [ ] Admin account — you need org admin access for governance steps
- [ ] Team, Business, or Enterprise tier — GhostForge publishing requires the
app_publishbilling feature - [ ] Browser with a modern rendering engine (Chrome, Firefox, Safari, Edge)
- [ ] (Optional)
curlorhttpiefor the API-driven publishing step - [ ] (Optional) Second user account for testing visibility and approval flows
Verify prerequisites
bash
# Backend health
curl -s http://localhost:8000/health | python3 -m json.tool
# GhostForge org status
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/org-policy-status | python3 -m json.toolExpected: { "enabled": true } (or false if not yet enabled — that's Step 1).
Step 1: Enable GhostForge
Duration: 3 minutes Goal: Enable GhostForge for your organization and verify the UI elements appear.
1.1 Open the Admin Dashboard
Navigate to the Admin Dashboard in the GhostAI UI (click your avatar > Admin, or use the admin link in the sidebar).
1.2 Go to the GhostForge tab
Click the GhostForge tab in the admin configuration section.
1.3 Enable GhostForge
Toggle Enable GhostForge to ON.
Set the initial configuration:
- Default Visibility: Organization
- Require Admin Approval: OFF (we'll enable this later in Step 7)
- Block PII Publishing: OFF (we'll test this in Step 6)
- Max Apps Per User: -1 (unlimited)
Click Save.
1.4 Verify
Refresh the main GhostAI chat page. You should now see:
- Browse Gallery button in the sidebar
- My Apps button in the sidebar
Click Browse Gallery — the gallery page should load (empty for now).
1.5 Verify via API
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/org-policy-statusExpected: { "enabled": true }
Step 2: Create a Canvas App
Duration: 3 minutes Goal: Build an interactive canvas that we'll publish to GhostForge.
2.1 Create a canvas
In the GhostAI chat, type:
Build an interactive sales KPI dashboard with 4 cards: Total Revenue ($2.4M, +12% from last quarter), New Customers (847, +23%), Average Deal Size ($28K, -3%), and Win Rate (34%, +5pp). Add a bar chart showing monthly revenue for the past 6 months and a donut chart showing revenue by product line. Make it responsive and professional with a dark theme.2.2 Verify the canvas
The canvas should render in the side panel with:
- Four KPI cards with values and trend indicators
- A bar chart for monthly revenue
- A donut chart for product line breakdown
- Dark theme styling
- Responsive layout
2.3 Test the canvas controls
- Click the tablet viewport toggle — verify responsive reflow
- Click the mobile viewport toggle — verify mobile layout
- Click the theme toggle — verify it switches to light mode and back
- Click the dev console button — verify you can see the HTML/CSS/JS source
Step 3: Publish to GhostForge
Duration: 5 minutes Goal: Publish the canvas as a GhostForge app and understand the publishing flow.
3.1 Open the publish modal
Click Publish to GhostForge on the canvas toolbar.
3.2 Fill in the app details
| Field | Value |
|---|---|
| Title | Sales KPI Dashboard |
| Description | Interactive sales metrics dashboard with revenue trends, customer growth, deal size, and win rate. Responsive dark theme. |
| Category | Productivity |
| Tags | dashboard, sales, kpi, metrics |
| Visibility | Organization |
| Slug | (auto-generated: sales-kpi-dashboard) |
3.3 Review the PII scan
Before publishing, GhostForge scans the canvas HTML for PII. Check the scan results:
- PII entities found: Should be 0 (the dashboard uses synthetic data)
- Privacy badge: PII-Free (green)
3.4 Publish
Click Publish. You should see:
- Success notification: "App published to GhostForge"
- A link to the published app appears in the chat
- The publish modal closes
3.5 Verify the published app
Click the link or navigate to /apps/sales-kpi-dashboard. The App Detail Page should show:
- Live preview of the dashboard
- Title, description, author name, organization
- Privacy badge (PII-Free, green)
- View count: 1
- Fork count: 0
- Fork, Embed, and Open buttons
3.6 Verify via API
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/sales-kpi-dashboard | python3 -m json.toolExpected response includes "slug": "sales-kpi-dashboard", "status": "published", "privacy_badge": "pii-free", "visibility": "org".
Step 4: Browse the Gallery
Duration: 3 minutes Goal: Use the gallery to discover apps.
4.1 Open the gallery
Click Browse Gallery in the sidebar or navigate to /apps.
4.2 Verify gallery features
- The Sales KPI Dashboard should appear as an app card
- The card shows: title, description preview, author, privacy badge, view count
4.3 Test search
Type "sales" in the search bar. The dashboard should appear in results.
4.4 Test category filter
Click "Productivity" in the category filters. The dashboard should appear.
4.5 Test sort
Switch between Recent, Popular, and Trending sort options. With only one app, the results will be the same — but point out that the sort algorithm considers view velocity and fork rate.
4.6 Gallery API
bash
# Search
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
"http://localhost:8000/api/apps/gallery?search=sales&sort=recent" | python3 -m json.tool
# Categories
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/gallery/categories | python3 -m json.toolStep 5: Fork an App
Duration: 3 minutes Goal: Fork an existing app and customize it.
5.1 Fork from the detail page
Navigate to the Sales KPI Dashboard detail page. Click Fork.
5.2 Verify the fork
A new chat session opens with the forked canvas loaded. The canvas should be identical to the original dashboard.
5.3 Customize the fork
Type:
Change this to a Marketing KPI dashboard. Replace the metrics with: Website Traffic (1.2M visits, +18%), Lead Conversion (4.2%, +0.8pp), Campaign ROI (3.2x, +0.4x), and Email Open Rate (28%, +2pp). Change the bar chart to show leads by channel and the donut to show spend by campaign.5.4 Verify the customized fork
The canvas should update with marketing-specific metrics while keeping the same layout and dark theme.
5.5 (Optional) Publish the fork
Publish the forked version as "Marketing KPI Dashboard". The detail page will show "Forked from Sales KPI Dashboard."
5.6 Fork API
bash
curl -s -X POST -H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
http://localhost:8000/api/apps/{app_id}/fork | python3 -m json.toolExpected: { "session_id": "...", "canvas_id": "...", "forked_app_id": "...", "message": "..." }
Step 6: PII Scanning and Blocking
Duration: 5 minutes Goal: Test the PII detection pipeline and the org-level PII blocking policy.
6.1 Create a canvas with PII
In a new chat, type:
Build a customer contact card for John Smith (john.smith@acme.com, 555-123-4567, SSN: 123-45-6789). Show their photo placeholder, name, email, phone, department (Engineering), and start date (2023-01-15).6.2 Try to publish
Click Publish to GhostForge. In the publish modal:
- PII scan results: Should detect email, phone number, SSN, and person name
- Privacy badge: PII-Warning (red)
- The Publish button should still work (PII blocking is OFF)
Fill in the details and publish. Note the red privacy badge on the app card.
6.3 Enable PII blocking
Go to Admin Dashboard > GhostForge > toggle Block PII Publishing to ON. Save.
6.4 Try to publish another PII-containing app
Create another canvas with PII:
Build an employee directory showing Jane Doe (jane.doe@corp.com, x4567) and Bob Wilson (bob.wilson@corp.com, x8901).Try to publish. The publish modal should show:
- PII entities detected
- Publish button is disabled with a message: "Publishing blocked — PII detected. Remove PII or contact your org admin."
6.5 Verify the policy works
The app cannot be published until either:
- The PII is removed from the canvas
- The org admin disables PII blocking
6.6 Disable PII blocking for subsequent demos
Go back to Admin Dashboard > GhostForge > toggle Block PII Publishing to OFF. Save.
Step 7: Org Admin Approval Workflow
Duration: 5 minutes Goal: Enable the approval queue and walk through the full approve/reject cycle.
7.1 Enable approval
Admin Dashboard > GhostForge > toggle Require Admin Approval to ON. Save.
7.2 Publish an app (as a regular user)
Create a simple canvas:
Build a simple Pomodoro timer with a 25-minute countdown, start/pause/reset buttons, and a session counter. Play a sound when the timer completes.Publish it as "Pomodoro Timer" with category "Productivity."
7.3 Verify pending status
The publish succeeds, but the app status is Pending Review — not published. It does NOT appear in the gallery.
Check My Apps — the Pomodoro Timer shows status "Pending Review."
7.4 Review as admin
Navigate to Admin Dashboard > GhostForge > Approval Queue.
The Pomodoro Timer should appear with:
- Title: Pomodoro Timer
- Author: your name
- PII status: PII-Free
- Privacy badge: green
7.5 Approve the app
Click Approve. The app status changes to Published and it now appears in the gallery.
7.6 Test the reject flow
Publish another simple app and this time Reject it with notes: "Please add a description before publishing."
Verify:
- The app returns to draft status
- The author sees the rejection notification with the admin's notes
7.7 Approval API
bash
# List pending approvals
curl -s -H "Authorization: Bearer $ADMIN_API_KEY" \
http://localhost:8000/api/admin/ghostforge-approvals | python3 -m json.tool
# Approve
curl -s -X POST -H "Authorization: Bearer $ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "approved", "notes": "Looks good."}' \
http://localhost:8000/api/admin/ghostforge-approvals/{approval_id}/review | python3 -m json.tool7.8 Disable approval for subsequent demos
Admin Dashboard > GhostForge > toggle Require Admin Approval to OFF. Save.
Step 8: Embedding and Distribution
Duration: 3 minutes Goal: Embed a published app and verify oEmbed and Open Graph support.
8.1 Get the embed code
From the Sales KPI Dashboard detail page, click Embed. Copy the iframe code.
8.2 Test the embed endpoint
bash
curl -s http://localhost:8000/api/apps/sales-kpi-dashboard/embed | head -50Expected: HTML page with the canvas content, sandboxed CSP headers, and "Powered by GhostForge" footer.
8.3 Test oEmbed
bash
curl -s http://localhost:8000/api/apps/sales-kpi-dashboard/oembed | python3 -m json.toolExpected: JSON oEmbed 1.0 response with type: "rich", html (iframe embed), width, height, title, author_name, provider_name: "GhostForge".
8.4 Test Open Graph
bash
curl -s http://localhost:8000/api/apps/sales-kpi-dashboard/og | head -30Expected: HTML page with <meta property="og:title">, <meta property="og:description">, <meta property="og:image"> tags for rich social previews.
8.5 Test in a local HTML page
Create a quick test page:
bash
cat > /tmp/embed-test.html << 'EOF'
<!DOCTYPE html>
<html>
<head><title>Embed Test</title></head>
<body>
<h1>Embedded GhostForge App</h1>
<iframe
src="http://localhost:8000/api/apps/sales-kpi-dashboard/embed"
width="100%"
height="600"
frameborder="0"
sandbox="allow-scripts allow-same-origin">
</iframe>
</body>
</html>
EOF
open /tmp/embed-test.htmlThe dashboard should render inside the iframe.
Step 9: Analytics
Duration: 3 minutes Goal: View per-app and org-level analytics.
9.1 Generate some views
Open the Sales KPI Dashboard detail page a few times (or use curl):
bash
for i in $(seq 1 5); do
curl -s -X POST -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/{app_id}/view
done9.2 View per-app analytics
Go to My Apps in the sidebar. Click the analytics icon (chart) on the Sales KPI Dashboard card.
The analytics panel should show:
- View count: 5+ (depending on your browsing)
- Fork count: 1 (from Step 5)
- Version history: version 1 (initial publish)
9.3 Analytics API
bash
# Per-app analytics
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/analytics/app/{app_id} | python3 -m json.tool
# Org summary
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/analytics/summary | python3 -m json.tool9.4 Org-level summary (executive view)
Navigate to Admin Dashboard > executive metrics. The GhostForge section shows:
- Total published apps
- Total views across all apps
- Active authors count
- Most popular apps
Step 10: API-Driven Publishing
Duration: 5 minutes Goal: Publish an app programmatically using the REST API.
10.1 Publish via API
bash
curl -s -X POST -H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "API Status Page",
"description": "A simple status page showing API endpoint health, published via the GhostForge API.",
"content": "<!DOCTYPE html><html><head><style>body{font-family:system-ui;background:#0f172a;color:#e2e8f0;padding:2rem;max-width:800px;margin:0 auto}h1{color:#38bdf8}.status{display:flex;align-items:center;gap:0.5rem;padding:0.75rem;background:#1e293b;border-radius:0.5rem;margin:0.5rem 0}.dot{width:10px;height:10px;border-radius:50%;background:#4ade80}.dot.warn{background:#fbbf24}.dot.down{background:#f87171}</style></head><body><h1>API Status</h1><div class=\"status\"><span class=\"dot\"></span><span>/api/chat — Operational</span></div><div class=\"status\"><span class=\"dot\"></span><span>/api/apps — Operational</span></div><div class=\"status\"><span class=\"dot warn\"></span><span>/api/phd — Degraded</span></div><div class=\"status\"><span class=\"dot\"></span><span>/api/memory — Operational</span></div><p style=\"color:#64748b;margin-top:2rem\">Last updated: <span id=\"ts\"></span></p><script>document.getElementById(\"ts\").textContent=new Date().toLocaleString()</script></body></html>",
"category": "productivity",
"tags": ["status", "api", "monitoring"],
"visibility": "org"
}' \
http://localhost:8000/api/apps | python3 -m json.tool10.2 Verify the published app
Expected response includes:
"status": "published"(or"pending_review"if approval is enabled)"slug": "api-status-page""privacy_badge": "pii-free""pii_detected": false
10.3 View in the gallery
Navigate to /apps/api-status-page. The status page should render with green/amber dots.
10.4 Update via API
bash
curl -s -X PUT -H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Updated status page with real-time health checks.",
"changelog": "Added PhD API degraded status indicator"
}' \
http://localhost:8000/api/apps/{app_id} | python3 -m json.toolThe version number increments and the changelog is recorded.
10.5 List your apps
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/mine | python3 -m json.tool10.6 Archive via API
bash
curl -s -X POST -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/apps/{app_id}/archive | python3 -m json.toolThe app is removed from the gallery but not deleted. It can be restored.
Troubleshooting
GhostForge not enabled
Symptom: /api/apps/org-policy-status returns { "enabled": false } or sidebar buttons are missing.
Fix: Admin Dashboard > GhostForge > toggle "Enable GhostForge" to ON. If the tab is not visible, your account may not have admin privileges.
Publish returns 403
Symptom: POST /api/apps returns 403 Forbidden.
Fix:
- Verify your account tier includes
app_publish(Team, Business, or Enterprise) - Verify GhostForge is enabled for your org
- Check if you've hit the max apps per user limit
PII blocking prevents publish
Symptom: Publish modal shows "Publishing blocked" with PII entities listed.
Fix: Either remove PII from the canvas content, or ask your org admin to disable "Block PII Publishing" in the GhostForge admin settings.
Gallery search returns no results
Symptom: Search query returns empty results even though apps exist.
Fix: Verify the apps are in "Published" status (not draft, pending, or archived). Private apps don't appear in gallery search — only "Organization" and "Public" visibility apps are searchable.
Embed shows blank page
Symptom: The /api/apps/{slug}/embed endpoint returns an empty or error page.
Fix:
- Verify the app is published and has content
- Verify the slug is correct
- Check that the app visibility allows the current viewer (private apps can't be embedded for others)
Approval queue empty despite pending apps
Symptom: Apps were published with approval required, but the queue shows nothing.
Fix: The approval queue only shows apps from your organization. Verify you're logged in as an org admin for the correct organization.
What's Next
- Canvas: Learn to build interactive canvases with the Canvas Demo Script
- Demo Practice: Run the GhostForge Demo Script for a polished customer presentation
- Admin Guide: See the GhostForge Configuration docs for the full admin reference
- Feature Docs: Read the GhostForge feature documentation for the complete feature overview
- GhostScience: Publish computation results as apps — combine with the GhostScience Full Lab
Lab Summary
| Step | Topic | Duration |
|---|---|---|
| 1 | Enable GhostForge | 3 min |
| 2 | Create a Canvas App | 3 min |
| 3 | Publish to GhostForge | 5 min |
| 4 | Browse the Gallery | 3 min |
| 5 | Fork an App | 3 min |
| 6 | PII Scanning and Blocking | 5 min |
| 7 | Org Admin Approval Workflow | 5 min |
| 8 | Embedding and Distribution | 3 min |
| 9 | Analytics | 3 min |
| 10 | API-Driven Publishing | 5 min |
| Total | ~38 min |