Skip to main content
Publishing makes an agent version available for installation.

​
Publish with guild agent save

You can save, validate, and publish in one command:

​
Key flags

  • --message: Sets the version message for this save.
  • --wait: Blocks until validation passes.
  • --publish: Publishes after a successful save. It implies --wait, so it always waits for validation and publish to finish, then prints Version is now published and available in the catalog.
  • --timeout <seconds>: Bounds how long the command waits for validation and publish (default: 300). Must be a positive integer.
  • --bump: Chooses which part of the version increments (major, minor, or patch) when deriving the next published version. Non-TypeScript agents (GUILD_NATIVE, GOOSE, and OPENCLAW) honor this level; the default is patch.

​
Publish separately

If you already saved a draft version, you can publish later:
To wait for validation before publishing:
To customize the wait timeout budget (in seconds, default is 300):
The --timeout option overrides the wait budget for both the validation wait and the publish wait. It must be a positive integer; providing an invalid value causes the command to exit with code 1.

​
Visibility and who can install

Agents have three visibility states:
  • Draft: no published version. The agent is not available for installation. Organization members can see it in the organization Browse tab with a draft badge.
  • Internal: published with visibility restricted to your organization (is_public=false). Not listed on Agent Hub, but installable by workspaces in your account, and organization members can find it from the organization Browse tab and category pages. Displayed with an internal badge.
  • Public: published and listed on Agent Hub (is_public=true). Installable by anyone. Organization members also see it in the organization Browse tab and category pages. Displayed with a public badge.
Archiving is separate from visibility. An archived agent is hidden from listings and blocked from new installs, though existing installs keep working. Publishing with guild agent save --publish or guild agent publish makes the agent Internal by default. An agent must already have a published version before it can go On-Hub. Selecting Public on a Draft agent is rejected with a 403 Forbidden error, so publish a version first. To make an agent public, use the agent settings page:
  1. Open the agent in app.guild.ai and go to its settings page.
  2. Select Public visibility. This marks the form as unsaved and enables Save.
  3. Click Save. A publish confirmation dialog appears before the change commits.
  4. Confirm the dialog. The visibility change commits atomically with any other unsaved settings (avatar, tags, maintainer, and archive status).
If the save fails, the form retains the Public selection so you can fix the issue and retry without re-selecting.
Making an agent public is permanent. Once an agent is public (is_public=true), you cannot revert it to a private or organization-only state. Attempting to change is_public from true to false is rejected with a 403 Forbidden error. Only operators can bypass this restriction.

​
Publish from the agent’s menu

You can also open the agent’s three-dot menu and select Publish to Agent Hub, then confirm the dialog. The item appears in one of three states: Once the agent is public, the menu shows View on Agent Hub in place of Publish to Agent Hub.

​
Moderation and discoverability

Guild can moderate an agent on the Hub to keep its discovery surfaces trustworthy. Most moderation only changes where the agent appears, but the two safety states also stop it running. The state appears as moderation_state on the agent in API responses. Ranked and curated lists are the home feed shelves, Browse all, and Top Creators. A DEMOTED agent is dropped from those but stays findable by name and on your profile, and it does not count toward your public agent tally on Top Creators. At UNLISTED and below it leaves discovery entirely and is reachable only by direct link, by you, or through an existing install.
DISABLED and TAKEN_DOWN are refused at run dispatch, so existing installs stop working, not just new ones. DISABLED also blocks new installs and is reversible; TAKEN_DOWN is a hard block.
Only Guild operators can set or clear a moderation state — you cannot change your own. Contact support if you believe an agent has been moderated in error.

​
What validation runs during --wait

--wait blocks until validation passes. Common failure modes:
  • TypeScript errors in agent.ts
  • Saving without being inside an agent directory (one with a guild.json file)
If validation fails, check the latest version and save again:

​
Update a published agent

To update an agent, save a new version and publish it:
To inspect status and version history:

​
Unpublish

To unpublish the latest published version:
Unpublishing moves the version from PUBLISHED back to DRAFT, so it leaves the catalog and is no longer installable. The command targets the latest published version and reports the transition on success. A version that is still in use cannot be unpublished. If any workspace has that version installed, the request is refused and the version stays published, so unpublishing never breaks an existing install. Remove the version from those workspaces first.

​
View your published agent in the UI

Open app.guild.ai, go to Agents, then click Add agent to browse the Agent Hub.