Publishing to the Marketplace

Once your plugin works locally, you can publish it to the Agentum marketplace. Other licensed users see it in their Marketplace tab, click Install, and get a one-click clone running on their machine. No emailing zip files; no telling people where to drop folders.

The whole flow is in the desktop app — there’s no CLI, no admin form, no separate developer portal. About 30 seconds from “I’m done editing” to “anyone with a license can install this.”

Before you start

You need:

  • An active license — trial or lifetime, both work.
  • Agentum running with a plugin folder in your plugins directory that you’d like to share.
  • A manifest.json in that folder with at minimum: 
    {
  "id": "your-plugin-id",
  "version": "1.0.0",
  "name": "Your Plugin Name",
  "uses": [],
  ...
}

    id becomes your agent’s public slug — pick it carefully, it can’t be renamed later. Stick to lowercase letters, digits, and hyphens. version must be a valid semver (1.0.0, 1.0.0-beta.1, etc.) — the marketplace rejects anything else.

If you don’t have a plugin yet, see Authoring Agents.

Becoming a publisher

A one-time step. The first time you open the publish flow, Agentum asks you to pick:

  • Publisher slug — your public handle. Lowercase letters, digits, hyphens, 1–40 chars. Shown next to your agents in the marketplace (“by your-slug”). This can’t be changed later — pick something you’ll be comfortable with.
  • Display name — the human name shown alongside your slug. This one can be edited later.

Click Become a publisher and you’re in. Your publisher account is now linked to your license; if you move to a different machine and activate the same license, you’re still the same publisher there.

Publishing a version

  1. Open Agentum and click Marketplace in the sidebar.
  2. Click + Publish an agent in the top-right of the catalog page.
  3. Pick the plugin to publish from the list. Agentum scans your plugins folder for anything with a manifest.json; warnings (missing version, mismatched id) appear inline so you can fix them before continuing.

  4. Fill in the details:

    • Display name — pre-filled from manifest.name. This is the headline on your agent’s card.
    • Description — one short line, ~120 characters. The hook that makes someone click into your card from the grid.
    • Category — pick from the dropdown. Drives where your agent appears in the marketplace sidebar.
    • Channel — stable or beta. Most versions are stable. Pick beta when this version is experimental and you want to limit who sees it (only users who explicitly opt in to your beta channel get beta updates).
    • Tags — comma-separated, free-form. Show up as chips on your detail page. Pick 2–4 specific words.
    • Screenshots — up to 5 images (PNG, JPEG, GIF, WebP; 5 MB each). These are the single biggest factor in whether someone installs you. See “What makes a good listing” below.
    • README — full markdown. Renders above the version list on your public marketplace page. This is where you explain what the plugin does, why it’s useful, what it needs, and what to expect.
    • Changelog — what changed in this version. Renders on the version’s detail page; users see this when they update.
  5. Click Publish v1.0.0 (or whatever your version is).

Agentum tarballs your plugin folder, uploads it, uploads each screenshot, and finalizes the version with the marketplace. You’ll see a success card with your slug and version when it’s live — usually 5–30 seconds.

What makes a good listing

The marketplace card is small. Visitors scan a grid. You’re competing with ~20 other agents for the click.

Display name — write it like a product, not a project. “Polymarket Pulse” beats “polymarket_v2.”

Description — what does it DO in one breath? “Real-time prediction-market dashboard” beats “Tool for tracking markets I follow with a custom UI and event handlers.” Drop adjectives.

Screenshots — show the actual UI, not the README. The first screenshot should show the plugin at work, not the install screen or a logo card. If your plugin’s primary surface is a Telegram bot, screenshot the chat. If it’s a dashboard panel, screenshot the panel.

README — assume the reader has never heard of your plugin and only opens it because the screenshot was compelling. Lead with: what it does, what you need to set up (integrations, API keys), what it does NOT do. Keep it under a screen of scrolling. Long READMEs lose people.

Tags — practical, not aspirational. “calendar, reminders” tells people what you fit; “ai, productivity, life-changing” tells them nothing.

Bumping versions

To publish a fix or a new feature: edit manifest.json in your text editor, bump the version, save. The marketplace enforces semver:

  • Patch (1.0.0 → 1.0.1) — bug fixes. Most users get this automatically the next time they check for updates.
  • Minor (1.0.0 → 1.1.0) — new features. Same auto-update behavior, but see “Permission changes” below.
  • Major (1.0.0 → 2.0.0) — breaking changes. You might want a fresh README section explaining what changed.
  • Pre-release (1.1.0 → 1.1.1-beta.1) — a beta. Only users who have explicitly switched your plugin to the beta channel see these.

Then open the publish wizard, pick the same plugin, and walk through. The slug is the same; the new version becomes the latest for users on its channel.

If you try to publish the same version twice, the wizard tells you to bump.

Permission changes

manifest.uses is the list of capabilities your plugin needs — things like scheduler, http, filesystem. Users see this list when they install you the first time.

When you publish an update, the marketplace compares the new uses list to what the user already has installed:

  • If the list is the same → silent update; user clicks Update and you’re in.
  • If you remove a capability → silent update.
  • If you add a capability → the Update button labels itself “Review & update” and pops a dialog showing exactly what’s new. The user can approve or cancel.

This isn’t a punishment; it’s how the marketplace keeps users in control of what their agents can do. But it’s also a cost: every added permission risks a user clicking Cancel and staying on your old version. Some practical implications:

  • Don’t over-declare in your first version. It’s tempting to add filesystem “just in case” — but if you don’t need it, leaving it out and adding it in v2 when you actually use it gives users an informed re-consent moment.
  • Group permission expansions into a single major bump. If you know v2 will add three new permissions, batch them rather than spreading across 2.1, 2.2, 2.3 — the user sees one dialog, not three.
  • Removing a permission is always free. If you can shrink uses, do it.

Yanking a version

Sometimes you ship a version with a real bug. To stop new users from getting it, ask in support — for now, yanking is an admin/curl action while we build the in-app surface.

When a version is yanked:

  • It disappears from the marketplace’s update suggestions.
  • It disappears from the public version list on your detail page.
  • Users who already have it installed can still keep it or reinstall it if their copy gets corrupted.
  • The fix is to publish a patch version (1.0.1) that supersedes the bad one. Users on the bad version auto-update to the patch.

So in practice: publish 1.0.1 with the fix, then ask support to yank 1.0.0. The marketplace handles the rest.

What can go wrong

The wizard maps every server error to a plain hint, but a few worth knowing about in advance:

  • “You already published this version.” Bump manifest.version in your text editor before re-publishing.
  • “A different publisher already owns this slug.” Someone else published your-plugin-id first. Rename manifest.id to something unique.
  • “manifest.json is missing ‘version’.” Add a "version": "1.0.0" field to your manifest.
  • “Wants new permissions: …” (during update) This is informational, not an error — your update added permissions the user hadn’t consented to. The user gets to decide whether to accept.
  • “One of your screenshots exceeds the 5 MB cap.” Resize the image (Preview → Tools → Adjust Size on macOS).
  • “Your publisher is suspended.” Contact support. We’d rather work it out than block you indefinitely.

What admins can do

Agentum admins have moderation tools, mostly invisible to publishers unless they need to be used:

  • Verify your publisher — a blue badge next to your name. Cosmetic, no other effect.
  • Suspend your publisher — blocks new publishes, hides existing agents until reinstated. Used for clear policy violations (DMCA, spam, abuse).
  • Suspend a specific agent — only that listing disappears; other agents you own keep working. Used for individual content issues.
  • Yank a specific version — see “Yanking a version” above.

If you find your agent has vanished from the public marketplace, contact support. We don’t act without a reason and we’ll tell you what happened.

Next steps