Hermes Bot Forge

Describe the job. Reuse what fits; provision a new Bot when it needs its own persistent role.

hermes plugins install bot-forge

Bot Forge is a Hermes Agent plugin that lets any agent spawn a complete, working Bot Mode Bot from one sentence — no New Agent dialog, no setup:

Creation failures attempt cleanup of that Bot. Sign-in and gateway readiness may remain pending; the result says which. A team is not an all-or-nothing transaction.

Does this job need a new Bot?

For a generic job or team request, the existing bundled skill asks the caller to inspect the roster and relevant skills/routines first. Reuse an existing owner, a skill, temporary delegation or a routine when sufficient. Create a new profile for a justified persistent responsibility, state or configuration difference, not just a new specialty. Profiles are not security sandboxes.

This is advisory guidance, not a deterministic classifier or a new planning service. Explicit authorized profile creation remains direct, with the existing duplicate and safety checks. The same decision applies to each proposed team member.

Demo

1. Ask any Bot for a new teammate. It checks the roster, designs the Bot and calls create_agent — the new Bot (Inkwell) appears in the roster while it works:

2. The new Bot is already alive. Its Bot Chat opens with it introducing itself:

Onboarding

1. Requirements

• Hermes Agent 0.21+ with the hermes CLI on your PATH
• Hermes Desktop for Bot Mode (the CLI works too — Bots are profiles)
• Linux and macOS are tested. Windows is not supported. Nobody runs the suite on Windows and no release has been tried there. The reports that do come from Windows have been real breakage — a manifest the doctor could not read (#41), a plugin that would not load on a clean install (#38). Gateway services, sandboxes and Bot Screen are skipped there by design. Creating a Bot from the CLI may well work — it is simply not a claim this project can make yet. Fixes are welcome

PyYAML is installed for you: plugin.yaml declares it under python_dependencies, and hermes plugins install puts it in the environment the plugin runs in, re-applying it after later updates. Nothing to add to your own environment; --no-deps skips it if you manage Python packages yourself.

2. Install

hermes plugins install BkashJEE/hermes-bot-forge

3. Enable it where you chat

Plugins are opt-in per profile. Enable Bot Forge on each profile that should be able to create Bots — your main profile, and any "manager" Bot:

hermes plugins enable bot-forge              # the default profile
hermes -p ceo plugins enable bot-forge       # a Bot named "ceo"

If enable asks to grant tool overrides, answer no — Bot Forge doesn't override anything.

4. Restart Hermes

hermes gateway restart
# With independent legacy services, restart their owners instead; do not create new services here.

Then quit and reopen Hermes Desktop.

5. Check it's loaded

hermes bot-forge-doctor

It tells you exactly what is missing — a profile you forgot to enable, a gateway still running the old code (the usual reason the tools never appear), a model that needs a per-Bot sign-in, and which sandbox backends this machine can run. Or, the long way:

hermes plugins list | grep bot-forge

Or ask your agent: "what tools do you have for creating agents?" — it should name create_agent, update_agent, list_agents and the rest.

6. Make your first Bot

Open Bot Mode, click the Bot you enabled, and type:

make me a bot that writes x.com posts and threads

Wait 1–3 minutes. The reply looks like:

🧪 Inkwell is alive — find it in Bot Mode.
job: turns ideas, links and demo notes into X posts and threads
brain: gpt-6-astra   tools: browser, file, web, …

Click the new Bot — its Bot Chat already has its introduction.

7. Choose how new Bots sign in

Unless given an explicit route, new Bots retain the existing model inheritance behavior. create_agent.model, create_team.lead.model and create_team.members[].model accept:

{"default": "<model-id>", "provider": "<provider-id>"}

Optional base_url and api_mode travel with that route. The complete block is applied before the first inference, without carrying over the creator's provider transport settings. Creation-tool calls reject missing/empty names or providers and unsupported fields before spawning; credentials must never be supplied here. Omit model to inherit, rather than {}. This does not select tiers automatically or authorize changing providers/budgets. An omitted team-member route inherits the calling profile as before, not the newly configured team lead.

Whether the selected model can be used right away depends on the provider:

Shared operating policy

One file — ~/.hermes/shared/BOT-POLICY.md — holds the rules that apply to every Bot: spend nothing without asking, never paste a secret, report what you didn't check. create_agent inlines it into each Bot's SOUL.md, so one edit reaches every Bot on the next build instead of being pasted into N copies that drift apart. The file is created with a short starter policy on first use; edit it to taste.

$EDITOR ~/.hermes/shared/BOT-POLICY.md   # edit once
check_policies                            # → which Bots are now stale

check_policies reports stale (built before your edit) and no_shared_policy (opted out), read-only. A Bot can opt out with "shared_policy": false in its spec. It audits only Bots forge created, so every row it prints is one you can act on.

To bring a stale Bot up to date, run update_agent with refresh_shared_policy: true — it re-injects the policy in place and keeps the Bot's identity and persona. (create_agent refuses a name that is already taken, so re-running it is not how you refresh an existing Bot.) It refuses a Bot whose SOUL.md has no content of its own, rather than handing one house rules and no identity.

A policy edit is compared by its meaning, not its bytes: comments, line endings, bullet markers and the indentation shared by a whole block are ignored, but a sub-bullet added, removed or re-nested is a real change and shows up as drift.

This is prompt text, not enforcement: the policy sits in the Bot's system prompt and the model is asked to follow it, exactly as it is asked to follow the rest of SOUL.md. Nothing blocks a tool call that breaks a rule. It borrows the discipline from steipete/agent-scripts — one canonical file, change once — but not its symlink mechanism, because a symlinked SOUL.md would give every Bot the same identity, and a pointer line would put the policy outside the system prompt. The reasoning, and the tests that hold it, are in docs/shared-policy.md.

Settings

Set per profile under plugins.entries.bot-forge.settings in that profile's config.yaml:

plugins:
  entries:
    bot-forge:
      settings:
        inherit_model: true
        fallback_model: {}
        probe_local_models: false
        install_gateway: true
        journal_enabled: true
        suggest_connectors: true
        allow_delete: false

| Key | Default | Meaning | |---|-