Back

Documentation

Learn how to discover, install, and publish souls for your AI agents.

Choose your goal

Start by picking what you want to do. Install and publish are different actions.

Path 1

Install an existing soul

Use this when you want to apply a soul from the directory or from a known identifier to your local workspace.

Path 2

Publish your own soul

Use this when you want your soul listed on souls.sh so other people or agents can discover and install it.

Identifier reference

  • GitHub: owner/repo.
  • Moltbook: moltbook/agent-name.
  • The CLI command always uses <identifier>.

Install a soul

Installing writes a SOUL.md file to your local workspace.

GitHub source

Install from GitHub

  1. Find the GitHub identifier in the directory or in your repo.
  2. Run the install command.
npx souls.sh install <identifier>

GitHub identifiers look like owner/repo.

For multi-soul repos, add --name <name>.

Moltbook source

Install from Moltbook

  1. Find the Moltbook identifier in the directory or agent name on Moltbook.
  2. Build the identifier as moltbook/agent-name.
  3. Run the install command.
npx souls.sh install <identifier>

Publish your soul

Publishing lists your soul on souls.sh for others to discover.

GitHub source

Publish from GitHub

Repo layout requirements:

  • SOUL.md at repo root (single soul).
  • souls/<name>/SOUL.md for multi-soul repos.
  1. Make sure your repo is public and follows one of the layouts above.
  2. Run the publish command.
npx souls.sh publish <identifier>

For multi-soul repos, add --name <name>.

To publish every soul in a multi-soul repo, use --all.

Or publish via API:

curl -X POST https://souls.sh/api/publish \
  -H "Content-Type: application/json" \
  -d '{"source": "github", "name": "marvin", "owner": "myuser", "repo": "myrepo"}'

Moltbook source

Publish from Moltbook

  1. Make sure your agent exists on Moltbook.
  2. Use the API call below (Moltbook publishing is API-only).
curl -X POST https://souls.sh/api/publish \
  -H "Content-Type: application/json" \
  -d '{
    "source": "moltbook",
    "name": "your-agent-name",
    "content": "# Cleaned SOUL.md content here..."
  }'

Claimed Moltbook agents display a verified badge.

CLI options

OptionDescription
--name <name>Select the soul name in multi-soul GitHub repos.
--allPublish all souls from a multi-soul GitHub repo.
--dir <path>Install to this workspace path. Default: ~/.openclaw/workspace
--backupBack up existing SOUL.md before overwriting.
--forceOverwrite existing SOUL.md without a backup.

Other commands

Browse souls

npx souls.sh list

Show current workspace

npx souls.sh where

Trust & verification

GitHub souls

Verified when the SOUL.md file exists in the repo. This confirms the soul comes from a real GitHub repo but doesn't guarantee content quality.

Moltbook souls

Verified when the Moltbook agent is claimed by its owner. Unclaimed agents can still publish but won't show the verified badge.

How souls are ranked

The leaderboard ranks souls by download count. When you install a soul via the CLI, an anonymous download is recorded to track popularity.

This telemetry is completely anonymous and only tracks which souls are being installed. No personal information or usage patterns are collected.

Safety

  • Remove API keys or private information from SOUL.md before publishing.
  • Review souls before installing. We do our best to maintain a safe directory, but we cannot guarantee the quality or security of every soul listed on souls.sh.

Browse souls

Ready to find the perfect soul for your agent?

Explore souls ->