Publishing Your Dench App: A Complete Guide

You've built a Dench App. It works on your machine. Now what? This guide covers everything after the build: getting your app into the DenchClaw sidebar, sharing it with teammates, and publishing it to the clawhub.ai marketplace so others can install it.

Step 1: The Local App Workflow#

Before publishing anywhere, your app should be working locally in your own DenchClaw instance.

Where Apps Live#

All Dench Apps live in the apps/ directory of your workspace:

~/.openclaw-dench/workspace/
  apps/
    my-app.dench.app/
      .dench.yaml
      index.html
      app.js
      style.css

DenchClaw watches this directory. When you create or modify a .dench.app folder, the app appears automatically in your sidebar — no restart required.

Testing Your App#

Open your DenchClaw frontend at localhost:3100. Your app should appear in the left sidebar with the icon you specified in .dench.yaml. Click it to open as a full tab, or check if it renders as a widget if you configured display: widget.

Test checklist:

• App loads without console errors (check browser DevTools → Console)
• window.dench bridge is available (console.log(dench) should show the API object)
• Queries return data (await dench.db.query("SELECT 1 AS test") should work)
• All permissions in .dench.yaml are actually required (remove unused ones)
• App works with empty data (what happens if the CRM is empty?)

Step 2: The .dench.yaml Manifest#

Your manifest drives everything about how the app is displayed and what it can access. Here's a complete reference:

# Required fields
name: My App Name           # Displayed in sidebar and app header
version: 1.0.0              # Semantic version (used for update checks)
 
# Recommended fields
description: What this app does and why someone would want it
icon: bar-chart-2           # Lucide icon name (https://lucide.dev)
author: Your Name
 
# Permissions (only include what you actually need)
permissions:
  - read:crm
  - write:crm
  - http:external
  - chat:create
  - events:subscribe
  - cron:schedule
 
# Display configuration
display: tab                 # "tab" for full-page, "widget" for compact card
 
# Widget-specific (only when display: widget)
widget:
  width: 4                  # Grid columns (1-6)
  height: 2                 # Grid rows (1-4)
  refreshMs: 300000         # Auto-refresh interval in milliseconds
 
# Optional metadata
homepage: https://github.com/yourname/my-dench-app
license: MIT
tags:
  - analytics
  - sales
  - dashboard

Step 3: Sharing with Teammates#

If your team runs DenchClaw instances, sharing an app is as simple as sharing the .dench.app folder.

Option A: Git Repository#

Put your app in a git repository and have teammates clone it into their apps/ directory:

# Your app repo structure
my-dench-app/
  .dench.yaml
  index.html
  app.js
  README.md
 
# Teammate installs it
cd ~/.openclaw-dench/workspace/apps/
git clone https://github.com/yourname/my-dench-app my-app.dench.app

The folder name must end in .dench.app for DenchClaw to recognize it.

Option B: Direct File Share#

Zip the .dench.app folder and share it. The recipient unzips it into their apps/ directory.

Option C: DenchClaw Workspace Sync#

If your team shares a common workspace (e.g., via Dropbox or a shared NFS mount), apps in the shared apps/ directory are automatically available to all instances pointing to that workspace.

Step 4: Publishing to clawhub.ai#

The clawhub.ai marketplace lets anyone find and install Dench Apps with a single command.

Preparing for Publication#

Before publishing, make sure your app:

1. Has a complete .dench.yaml — name, version, description, author, homepage, license
2. Has a README.md — explain what it does, how to set it up, what permissions it needs and why
3. Handles empty states gracefully — new users won't have CRM data yet
4. Doesn't hardcode sensitive data — no API keys in source files
5. Works without network access (for read:crm apps) — test offline

Publishing via the clawhub CLI#

# Install the clawhub CLI if you haven't
npm install -g clawhub
 
# Login to clawhub.ai
clawhub login
 
# Navigate to your app folder
cd ~/.openclaw-dench/workspace/apps/my-app.dench.app
 
# Publish
clawhub publish
 
# Output:
# ✅ Published my-app@1.0.0 to clawhub.ai
# 🔗 https://clawhub.ai/skills/your-username/my-app

Publishing Updates#

When you release a new version:

1. Update the version field in .dench.yaml
2. Update your README.md with a changelog
3. Run clawhub publish again

DenchClaw users who have installed your app will see an update notification and can upgrade with clawhub update my-app.

Step 5: App Quality Guidelines#

For apps on the clawhub.ai marketplace, follow these guidelines to ensure quality:

Offline-First (for CRM apps)#

Apps using only read:crm should work even when the machine is offline — DuckDB is local. Test by disabling network access and verifying the app still loads.

Error Handling#

// Always handle query errors gracefully
try {
  const data = await dench.db.query("SELECT * FROM v_deals");
  renderDeals(data);
} catch (err) {
  showError('Unable to load deals. Check your CRM configuration.');
  console.error('Query failed:', err);
}

Mobile Considerations#

DenchClaw can be accessed via mobile companion apps. Test your app at 375px width (iPhone SE viewport) and ensure it's at least usable, even if not optimized.

Performance on First Load#

Aim for initial content visible within 500ms. Show a loading skeleton while data loads rather than a blank screen.

Frequently Asked Questions#

Can I publish a paid app on clawhub.ai?#

The clawhub.ai marketplace model for paid apps is planned but not yet released. Currently, all published apps are free.

How do I update an already-installed app?#

Teammates using your app via git can git pull in the app directory. For clawhub installations, they run clawhub update app-name. Direct file installs require re-copying the files.

Can I make my app private (not public on clawhub.ai)?#

Yes. When running clawhub publish, add the --private flag. Private apps are accessible only via direct share or within your organization account.

What's the difference between a skill and an app?#

Skills (SKILL.md files) teach the DenchClaw AI agent new capabilities — they're instruction sets for the agent, not UI. Apps (.dench.app folders) are web UIs that run inside DenchClaw and can call the agent. A complex feature might use both: a skill to give the agent the capability, and an app to provide a UI for triggering it.

Do apps run when DenchClaw is closed?#

No. Apps run as iframes inside the DenchClaw frontend. They're active only while the frontend is open. For background tasks, use dench.cron.schedule() — cron jobs run in the DenchClaw backend process regardless of whether the frontend is open.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →