Skip to content

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_publish billing feature
  • [ ] Browser with a modern rendering engine (Chrome, Firefox, Safari, Edge)
  • [ ] (Optional) curl or httpie for 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.tool

Expected: { "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-status

Expected: { "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 ​

FieldValue
TitleSales KPI Dashboard
DescriptionInteractive sales metrics dashboard with revenue trends, customer growth, deal size, and win rate. Responsive dark theme.
CategoryProductivity
Tagsdashboard, sales, kpi, metrics
VisibilityOrganization
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.tool

Expected response includes "slug": "sales-kpi-dashboard", "status": "published", "privacy_badge": "pii-free", "visibility": "org".


Duration: 3 minutes Goal: Use the gallery to discover apps.

Click Browse Gallery in the sidebar or navigate to /apps.

  • The Sales KPI Dashboard should appear as an app card
  • The card shows: title, description preview, author, privacy badge, view count

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.

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.tool

Step 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.tool

Expected: { "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.tool

7.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 -50

Expected: 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.tool

Expected: 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 -30

Expected: 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.html

The 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
done

9.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.tool

9.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.tool

10.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

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.tool

The 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.tool

10.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.tool

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

  1. Verify your account tier includes app_publish (Team, Business, or Enterprise)
  2. Verify GhostForge is enabled for your org
  3. 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.

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:

  1. Verify the app is published and has content
  2. Verify the slug is correct
  3. 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 ​


Lab Summary ​

StepTopicDuration
1Enable GhostForge3 min
2Create a Canvas App3 min
3Publish to GhostForge5 min
4Browse the Gallery3 min
5Fork an App3 min
6PII Scanning and Blocking5 min
7Org Admin Approval Workflow5 min
8Embedding and Distribution3 min
9Analytics3 min
10API-Driven Publishing5 min
Total~38 min

SOC 2 Type II Certified | BAA Available | HIPAA-Ready